Error Codes
Complete reference of HTTP status codes, error response formats, and SDK exception mappings.
Error Response Format
All error responses follow a consistent JSON format:
{
"error": {
"message": "A human-readable description of what went wrong"
}
}HTTP Status Codes
| Code | Meaning | Common Causes | Resolution |
|---|---|---|---|
| 200 | OK | Request succeeded | — |
| 204 | No Content | Successful delete operation | — |
| 400 | Bad Request | Invalid UUID format, missing required fields, invalid player_gender value, malformed JSON body | Check the request body matches the expected schema. Verify UUID format for persona and machine IDs. |
| 401 | Unauthorized | Missing or invalid JWT token, missing or invalid API key, invalid LLM API key | For web API: check Authorization: Bearer header. For SDK: check X-API-Key and X-LLM-API-Key headers. |
| 403 | Forbidden | Accessing another user's persona via SDK, accessing an unpublished persona, non-admin accessing admin endpoints | Ensure you own the persona and it is published. Use personas.list() to see accessible personas. |
| 404 | Not Found | Persona ID doesn't exist, session not found, machine ID doesn't exist | Verify the ID exists. For sessions, use get_session() to check before sending messages. |
| 429 | Too Many Requests | Rate limit exceeded | Wait for the Retry-After header duration. SDKs auto-retry with exponential backoff. |
| 500 | Internal Server Error | Unexpected server error, LLM provider outage, database error | Retry the request. If persistent, check your LLM provider's status page. SDKs auto-retry on 5xx errors. |
| 503 | Service Unavailable | Server is temporarily overloaded or under maintenance | Retry after a short delay. SDKs handle this automatically. |
SDK Exception Mapping
Each SDK maps HTTP status codes to typed exceptions:
| HTTP Code | Python | TypeScript | Unity (C#) |
|---|---|---|---|
| 400 | BadRequestError | BadRequestError | BadRequestException |
| 401 | AuthenticationError | AuthenticationError | AuthenticationException |
| 403 | ForbiddenError | ForbiddenError | ForbiddenException |
| 404 | NotFoundError | NotFoundError | NotFoundException |
| 429 | RateLimitError | RateLimitError | RateLimitException |
| 500+ | ServerError | ServerError | ServerException |
💡Tip
All SDKs automatically retry on 429 and 5xx errors with jittered exponential backoff (up to 3 retries by default, configurable via
max_retries). You only need to handle errors that persist after retries.Rate Limits by Category
| Category | Limit | Scope | Applies To |
|---|---|---|---|
| Generation | 10 / min | Per IP | AI content creation (web editor) |
| Chat | 60 / min | Per IP | Web chat message endpoints |
| General | 120 / min | Per IP | All other web endpoints |
| SDK Chat | 30 / min | Per API key | SDK message + streaming endpoints |
| SDK General | 60 / min | Per API key | SDK init, history, reset, personas, machines |