API: Error Codes

Error Response Format

All API errors return a JSON object with an error key containing a machine-readable code and a human-readable message.

{
  "error": {
    "code": "error_code_string",
    "message": "Description of what went wrong"
  }
}

Some validation errors include a details field with per-field information:

{
  "error": {
    "code": "unprocessable_entity",
    "message": "Validation failed",
    "details": {
      "name": "is required"
    }
  }
}

HTTP Status Codes

Error Code Reference

unauthorized

HTTP Status: 401

Returned when the API key is missing, invalid, or expired.

Possible causes: - No Authorization header in the request - The Bearer token does not match any active API key - The API key has been revoked from the dashboard - The API key has passed its expiration date

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

How to fix: - Verify your API key is included in the Authorization header as Bearer oc_live_... - Check that the key has not been revoked in Dashboard > Settings > API Keys - Generate a new key if the current one has expired

forbidden

HTTP Status: 403

Returned when your API key is valid but lacks the permissions for the requested action.

{
  "error": {
    "code": "forbidden",
    "message": "Access denied"
  }
}

How to fix: - Verify your account has access to the requested resource - Contact support if you believe this is an error

not_found

HTTP Status: 404

The requested resource does not exist or belongs to a different account. The API does not distinguish between "does not exist" and "belongs to someone else" for security reasons.

{
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  }
}

How to fix: - Verify the resource ID in your request URL - Use the list endpoints to find valid resource IDs - Confirm the resource has not been deleted

unprocessable_entity

HTTP Status: 422

The request was understood but cannot be processed. This covers validation errors and business logic constraints.

Common scenarios:

Starting an instance that is already running: json { "error": { "code": "unprocessable_entity", "message": "Instance is already running" } }

Deleting a subscription-based instance via API: json { "error": { "code": "unprocessable_entity", "message": "This instance cannot be deleted. Only daily billing instances can be deleted via API." } }

Invalid package selection during purchase: json { "error": { "code": "unprocessable_entity", "message": "Invalid package index. Please select a valid Claw package." } }

Restoring a backup while the instance is running: json { "error": { "code": "unprocessable_entity", "message": "Instance must be stopped or paused before restoring a backup." } }

How to fix: - Read the message field for specific guidance - Check the current state of the resource before performing actions - Use the Get Instance Details endpoint to verify can_start, can_stop, and can_restart fields

ratelimitexceeded

HTTP Status: 429

You have exceeded the rate limit of 100 requests per minute for your API key.

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again later."
  }
}

Rate limit headers are included in every response:

How to fix: - Wait until the X-RateLimit-Reset timestamp before retrying - Add delays between requests in automated scripts - Use the X-RateLimit-Remaining header to avoid hitting the limit

internal_error

HTTP Status: 500

An unexpected error occurred on the server. The error details are logged internally but not exposed in the response for security.

{
  "error": {
    "code": "internal_error",
    "message": "An internal error occurred"
  }
}

How to fix: - Retry the request after a short delay - If the error persists, contact support with the timestamp and endpoint you called

Troubleshooting Quick Reference

Related Docs

• API Overview — Authentication, rate limits, and response format
• Get Instance Details — Check action availability before calling
• Billing Endpoints — Billing-specific error scenarios