Error Codes

The Mirra SDK returns structured error responses that include an error code, human-readable message, and optional details. This reference documents all error codes, their causes, and recommended solutions.

Error response format

All API errors follow a consistent JSON structure:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      // Optional additional context
    }
  }
}

The success field is always false for errors. The code field contains a machine-readable error identifier. The message field provides a human-readable description. The optional details object contains additional context specific to the error.

HTTP status codes

The API uses standard HTTP status codes to indicate the general category of error:

Authentication errors

AUTHENTICATION_ERROR

Authentication failed or the API key is invalid.

Example response:

{
  "code": "AUTHENTICATION_ERROR",
  "message": "Invalid API key"
}

Common causes:

• Missing Authorization header
• Malformed API key
• Expired or revoked key

Solution: Verify your API key is correct and include the Authorization: Bearer YOUR_KEY header in every request. If the key is expired or revoked, generate a new one.

PERMISSION_DENIED

You do not have permission to perform this action.

Example response:

{
  "code": "PERMISSION_DENIED",
  "message": "You do not have permission to access this resource"
}

Common causes:

• Attempting to access another user's resource
• API key lacks required permissions
• Resource is restricted

Solution: Verify you own the resource. Check that your API key has the appropriate permissions. If necessary, use an API key with broader access or contact support if you believe you should have access.

Validation errors

VALIDATION_ERROR

Request data failed validation.

Example response:

{
  "code": "VALIDATION_ERROR",
  "message": "subdomain must be between 3 and 30 characters",
  "details": {
    "field": "subdomain",
    "value": "ab"
  }
}

The details object indicates which field failed validation and the value that was provided.

Common validation issues:

• Missing required fields
• Invalid field format
• Value out of allowed range
• Invalid enum value

Solution: Review the error message and details object to identify the problematic field. Ensure all required fields are present and meet the documented constraints.

INVALID_SUBDOMAIN

Subdomain format is invalid.

Example response:

{
  "code": "INVALID_SUBDOMAIN",
  "message": "Subdomain can only contain lowercase letters, numbers, and hyphens"
}

Subdomain requirements:

• 3 to 30 characters
• Lowercase letters, numbers, and hyphens only
• Must start with a letter
• Cannot start or end with a hyphen

Solution: Choose a subdomain that meets these requirements.

SUBDOMAIN_TAKEN

The requested subdomain is already in use.

Example response:

{
  "code": "SUBDOMAIN_TAKEN",
  "message": "The subdomain 'my-agent' is already taken"
}

Solution: Choose a different subdomain. If you believe you already own this subdomain, list your existing resources to verify.

MISSING_REQUIRED_FIELD

A required field is missing from the request.

Example response:

{
  "code": "MISSING_REQUIRED_FIELD",
  "message": "name is required",
  "details": {
    "field": "name"
  }
}

Solution: Include the missing field in your request. Refer to the API documentation for the endpoint to see all required fields.

Resource errors

NOT_FOUND

The requested resource does not exist.

Example response:

{
  "code": "NOT_FOUND",
  "message": "Agent not found"
}

Common causes:

• Invalid resource ID
• Resource was deleted
• Wrong endpoint

Solution: Verify the resource ID is correct. Check that the resource still exists by listing your resources. Ensure you are using the correct API endpoint.

AGENT_NOT_FOUND / SCRIPT_NOT_FOUND / RESOURCE_NOT_FOUND / TEMPLATE_NOT_FOUND

Specific resource type not found.

Example response:

{
  "code": "SCRIPT_NOT_FOUND",
  "message": "Script with ID '123abc' not found"
}

These error codes are more specific variants of NOT_FOUND that indicate which resource type was not found.

State errors

ALREADY_PUBLISHED

Resource is already published to the marketplace.

Example response:

{
  "code": "ALREADY_PUBLISHED",
  "message": "This agent is already published"
}

Solution: If you need to make changes, unpublish the resource first or update the published version directly using the update endpoint.

NOT_PUBLISHED

Attempting an action that requires the resource to be published.

Example response:

{
  "code": "NOT_PUBLISHED",
  "message": "This script must be published before it can be installed"
}

Solution: Publish the resource to the marketplace before attempting the action.

CANNOT_DELETE_PUBLISHED

Cannot delete a published resource.

Example response:

{
  "code": "CANNOT_DELETE_PUBLISHED",
  "message": "Cannot delete a published template. Unpublish it first."
}

Solution: Unpublish the resource first, then delete it. This prevents accidental deletion of resources that other users may have installed.

Dependency errors

INVALID_DEPENDENCY

A referenced dependency does not exist or is invalid.

Example response:

{
  "code": "INVALID_DEPENDENCY",
  "message": "Resource 'api_123' not found",
  "details": {
    "dependency": "api_123",
    "type": "resource"
  }
}

Common causes:

• Referenced script or resource does not exist
• Dependency is not published
• Circular dependencies

Solution: Verify all dependencies exist and are published. Check for circular references in your dependency graph.

Rate limiting errors

RATE_LIMIT_EXCEEDED

You have exceeded your rate limit.

Example response:

{
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded. Try again in 42 seconds.",
  "retryAfter": 42
}

The retryAfter field indicates how many seconds to wait before retrying.

Rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1699564800

Solution: Wait for the time specified in retryAfter before retrying. Implement exponential backoff in your application. Consider upgrading to a higher tier for increased rate limits.

Runtime errors

INVALID_CODE

Script code is invalid or failed validation.

Example response:

{
  "code": "INVALID_CODE",
  "message": "Script contains syntax errors",
  "details": {
    "line": 42,
    "error": "Unexpected token '}'"
  }
}

The details object provides the line number and specific error message.

Solution: Fix the syntax errors in your script code. Test your code locally before deploying.

INVALID_RUNTIME

Specified runtime is not supported.

Example response:

{
  "code": "INVALID_RUNTIME",
  "message": "Runtime 'python2.7' is not supported. Use 'nodejs18' or 'python3.11'"
}

Solution: Use a supported runtime: nodejs18 or python3.11.

System errors

INTERNAL_ERROR

An unexpected server error occurred.

Example response:

{
  "code": "INTERNAL_ERROR",
  "message": "An unexpected error occurred. Please try again."
}

Solution: Retry the request. If the error persists, contact support with the request ID from the response headers.

SERVICE_UNAVAILABLE

Service is temporarily unavailable.

Example response:

{
  "code": "SERVICE_UNAVAILABLE",
  "message": "Service temporarily unavailable. Please try again."
}

Solution: Wait and retry with exponential backoff. Check the service status page for ongoing incidents.

Error handling best practices

Implement retry logic

Implement exponential backoff for retryable errors such as rate limits and service unavailability:

async function retryRequest(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.code === 'RATE_LIMIT_EXCEEDED') {
        const delay = error.retryAfter * 1000;
        await new Promise(resolve => setTimeout(resolve, delay));
      } else if (i === maxRetries - 1) {
        throw error;
      } else {
        await new Promise(resolve => setTimeout(resolve, 2 ** i * 1000));
      }
    }
  }
}

This function retries failed requests with exponential backoff, respecting the retryAfter value for rate limit errors.

Handle errors by code

Handle different error codes appropriately in your application:

try {
  const agent = await mirra.agents.create({
    subdomain: 'my-agent',
    name: 'My Agent',
    systemPrompt: 'Hello!'
  });
} catch (error) {
  switch (error.code) {
    case 'SUBDOMAIN_TAKEN':
      console.error('Subdomain already exists');
      break;
    case 'VALIDATION_ERROR':
      console.error('Invalid data:', error.details);
      break;
    case 'RATE_LIMIT_EXCEEDED':
      console.error('Rate limited, retry in:', error.retryAfter);
      break;
    default:
      console.error('Unexpected error:', error.message);
  }
}

Log error details

Always log error details for debugging and monitoring:

console.error('API Error', {
  code: error.code,
  message: error.message,
  details: error.details,
  requestId: error.requestId, // If available
  timestamp: new Date().toISOString()
});

Include the request ID when available to help support diagnose issues.

Common error scenarios

Creating an agent

Publishing to marketplace

Installing templates

See also

• Quickstart - Get started with the Mirra SDK
• Authentication - API key management and security
• Scripts - Deploy serverless functions
• Resources - Create API integrations
• Templates - Bundle resources and scripts