Error Codes

Complete reference of Mirra SDK error codes and how to handle them

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 and authorization errors

AUTHENTICATION_ERROR

Authentication failed or credentials are missing.

Example response:

{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Authentication required"
  }
}

Common causes:

• Missing X-API-Key header
• Malformed API key
• Expired or revoked key

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

UNAUTHORIZED

The request is not authorized.

Example response:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Unauthorized"
  }
}

Common causes:

• Valid credentials but the session or token is not accepted
• Attempting an action that requires a different authentication level

Solution: Re-authenticate and retry the request.

PERMISSION_DENIED

You do not have permission to perform this action.

Example response:

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

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.

INVALID_API_KEY

The provided API key is not valid.

Example response:

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key"
  }
}

Common causes:

• Typo in the API key
• Using a key from a different environment
• Key has been deleted

Solution: Double-check the API key value. Generate a new key if needed.

Validation errors

VALIDATION_ERROR

Request data failed validation.

Example response:

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

The details object may indicate 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
• Duplicate key (e.g., subdomain already taken)

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_INPUT

The provided input is invalid.

Example response:

{
  "success": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "Invalid value for field 'runtime'"
  }
}

Common causes:

• Unsupported value for a known field
• Wrong data type

Solution: Check the API documentation for valid values and correct the input.

MISSING_REQUIRED_FIELD

A required field is missing from the request.

Example response:

{
  "success": false,
  "error": {
    "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:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource 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.

ALREADY_EXISTS

A resource with the same identifier already exists.

Example response:

{
  "success": false,
  "error": {
    "code": "ALREADY_EXISTS",
    "message": "A resource with this name already exists"
  }
}

Common causes:

• Creating a resource with a duplicate name or subdomain
• Re-creating a resource that was not fully deleted

Solution: Use a different name or identifier for the new resource.

CONFLICT

The request conflicts with the current state of the resource.

Example response:

{
  "success": false,
  "error": {
    "code": "CONFLICT",
    "message": "Resource is in a conflicting state"
  }
}

Common causes:

• Concurrent updates to the same resource
• Attempting an action that is invalid given the resource's current state

Solution: Fetch the latest state of the resource and retry the operation.

Rate limiting errors

RATE_LIMIT_EXCEEDED

You have exceeded your rate limit.

Example response:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded",
    "details": {}
  }
}

The details object may contain additional information about the rate limit.

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

Service errors

SERVICE_UNAVAILABLE

Service is temporarily unavailable.

Example response:

{
  "success": false,
  "error": {
    "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.

ADAPTER_ERROR

An error occurred in the underlying service adapter.

Example response:

{
  "success": false,
  "error": {
    "code": "ADAPTER_ERROR",
    "message": "Failed to execute operation",
    "details": {}
  }
}

Common causes:

• Third-party service failure
• Invalid adapter configuration
• Timeout communicating with an external service

Solution: Retry the request. If the error persists, check that the relevant integration is configured correctly.

OPERATION_FAILED

The requested operation could not be completed.

Example response:

{
  "success": false,
  "error": {
    "code": "OPERATION_FAILED",
    "message": "Operation failed"
  }
}

Common causes:

• An unexpected condition prevented the operation from completing
• Partial failure in a multi-step operation

Solution: Retry the request. Check the error message for more context on what went wrong.

Generic errors

INTERNAL_ERROR

An unexpected server error occurred.

Example response:

{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An internal error occurred"
  }
}

Solution: Retry the request. If the error persists, contact support.

UNKNOWN_ERROR

An unclassified error occurred.

Example response:

{
  "success": false,
  "error": {
    "code": "UNKNOWN_ERROR",
    "message": "An unexpected error occurred"
  }
}

Solution: Retry the request. If the error persists, contact support with details about the request that triggered the error.

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) {
      const response = error.response;
      if (response?.error?.code === 'RATE_LIMIT_EXCEEDED') {
        // Wait before retrying rate-limited requests
        await new Promise(resolve => setTimeout(resolve, 2 ** i * 1000));
      } 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.

Handle errors by code

Handle different error codes appropriately in your application:

const response = await fetch('/api/v1/scripts', {
  method: 'POST',
  headers: { 'X-API-Key': apiKey, 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'My Script', code: '...' })
});
 
const result = await response.json();
 
if (!result.success) {
  switch (result.error.code) {
    case 'VALIDATION_ERROR':
      console.error('Invalid data:', result.error.message, result.error.details);
      break;
    case 'ALREADY_EXISTS':
      console.error('Resource already exists');
      break;
    case 'RATE_LIMIT_EXCEEDED':
      console.error('Rate limited, retrying...');
      break;
    default:
      console.error('Unexpected error:', result.error.message);
  }
}

Log error details

Always log error details for debugging and monitoring:

if (!result.success) {
  console.error('API Error', {
    code: result.error.code,
    message: result.error.message,
    details: result.error.details,
    timestamp: new Date().toISOString()
  });
}

Common error scenarios

Creating a resource

Executing an operation

Authentication

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