Error Handling
Error Handling Reference
Every error response follows a consistent format with a machine-readable code, human-readable message, contextual details, and a request ID for debugging.
Error Response Format
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid payload: 'model' is required",
"details": {
"field": "model",
"rule": "required"
},
"requestId": "req_abc123def456"
}
}Error Codes
The request was malformed or missing required fields.
Common causes: Missing required field, invalid JSON, wrong data type
How to fix: Check the request body against the API reference. Validate with the SDK types.
Authentication failed or no credentials provided.
Common causes: Missing or expired API key, invalid token format
How to fix: Verify your API key is correct and not expired. Check the Authorization header format.
The token lacks permission for this action.
Common causes: Scoped token missing required scope, entity mismatch
How to fix: Check your token scopes. Ensure the X-Entity-ID matches the token entity.
The requested resource or face/action does not exist.
Common causes: Wrong face name, typo in action, deleted resource
How to fix: Verify the face and action names. Check that the resource exists.
The request conflicts with the current state.
Common causes: Duplicate idempotency key, concurrent modification, already exists
How to fix: Use a unique idempotency key. Fetch the latest state before modifying.
The request body failed validation.
Common causes: Invalid field value, constraint violation, business rule failure
How to fix: Check the details field for the specific validation failure.
Too many requests. You have exceeded your rate limit.
Common causes: Exceeding per-minute or per-face rate limits
How to fix: Implement exponential backoff. Check X-RateLimit-Reset for when to retry.
An unexpected error occurred on the server.
Common causes: Server bug, downstream service failure
How to fix: Retry with backoff. If persistent, contact support with the requestId.
The service is temporarily unavailable.
Common causes: Maintenance window, capacity limits, dependency outage
How to fix: Retry with backoff. Check the status page for ongoing incidents.
Retry Strategy
Not all errors are retryable. Here is a quick reference:
| Code | Retryable | Strategy |
|---|---|---|
| 400, 401, 403, 404, 422 | No | Fix the request and resubmit |
| 409 | Maybe | Re-fetch state, then retry |
| 429 | Yes | Wait for X-RateLimit-Reset, then retry |
| 500, 503 | Yes | Exponential backoff: 1s, 2s, 4s, 8s |
SDK Error Handling
The SDK throws typed EEError instances with structured properties for code, message, requestId, and retryability.
import { createClient, EEError } from '@evileye/sdk'
const ee = createClient({ token: process.env.EE_TOKEN!, entity: 'my-company' })
try {
const result = await ee.ai.generate({ prompt: 'Hello' })
console.log(result.data)
} catch (err) {
if (err instanceof EEError) {
console.error(`[${err.code}] ${err.message}`)
console.error('Request ID:', err.requestId)
if (err.retryable) {
// Safe to retry with backoff
console.log('Retrying in', err.retryAfter, 'ms')
}
}
}Related
- Rate Limits— rate limit tiers and handling 429 responses
- API Reference— complete endpoint documentation