Error Codes¶

All API errors return a JSON body with a consistent structure:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description.",
    "status": 401,
    "details": {},
    "request_id": "req_abc123",
    "timestamp": "2026-02-19T12:00:00Z"
  }
}

Error Code Reference¶

Authentication (401)¶

Code	Message	Description
`AUTHENTICATION_ERROR`	Authentication failed.	Generic authentication failure.
`INVALID_TOKEN`	The provided token is invalid.	API key is malformed or doesn't exist.
`EXPIRED_TOKEN`	The provided token has expired.	API key has passed its expiration date.

Authorization (403)¶

Code	Message	Description
`AUTHORIZATION_ERROR`	You do not have permission.	Generic permission failure.
`NOT_CLONE_OWNER`	You are not the owner of this clone.	The key's clone ownership check failed.
`INSUFFICIENT_PLAN`	Your plan does not support this feature.	Feature requires a higher plan tier.

Not Found (404)¶

Code	Message	Description
`NOT_FOUND`	Resource not found.	Generic not found.
`CLONE_NOT_FOUND`	Clone does not exist.	The API key's clone was deleted or doesn't exist.

Validation (422)¶

Code	Message	Description
`VALIDATION_ERROR`	The provided data is invalid.	Request body failed validation.

Rate Limit (429)¶

Code	Message	Description
`RATE_LIMIT_EXCEEDED`	Too many requests.	Per-key rate limit exceeded. See Rate Limits.

Server Errors (500/502)¶

Code	Message	Description
`INTERNAL_ERROR`	An internal server error occurred.	Unexpected server failure.
`LLM_SERVICE_ERROR`	The AI service is temporarily unavailable.	Upstream LLM provider issue.
`EXTERNAL_SERVICE_ERROR`	An external service is unavailable.	Dependency failure.

Handling Errors in SDKs¶

Both official SDKs map these codes to typed exception/error classes. See: