Errors
Interpret Eigenn API statuses, optional error fields, request IDs, and safe retry signals.
Public REST errors use an object whose fields are optional because individual operations can return narrower error shapes.
{
"error": "Unauthorized",
"message": "Invalid API key",
"description": "Authentication failed.",
"requestId": "req_01HXYZ1ABCD23EFGH456JK",
"retryAfterSeconds": 60
}Do not make a client fail to parse an error when one of these fields is absent.
Status Codes
| Status | Meaning | Typical action |
|---|---|---|
| 400 | Missing, malformed, or semantically invalid request | Correct the request before retrying. |
| 401 | Missing or invalid authentication | Replace or refresh the credential. |
| 403 | Valid credential without a required scope | Change the grant; repeating the request will not help. |
| 404 | Resource missing or inaccessible to the team | Verify the ID and team. |
| 409 | Conflict with current state or an in-flight idempotent request | Inspect state and Retry-After when present. |
| 422 | Request structure failed validation | Correct the fields named in the description. |
| 429 | Rate limit exceeded | Wait for Retry-After. |
| 500 | Unexpected server error | Retry a safe operation with backoff. |
Individual operations can document more specific 400 or 409 shapes. For example, invoice creation can return a message-only conflict when an invoice number is already used.
Request IDs
Normalized REST errors include X-Request-ID and can include the same value in requestId. Log it with:
- HTTP method
- endpoint
- status
- operation ID
- safe resource IDs
- client timestamp
Never log the bearer token or sensitive customer payload merely to preserve debugging context.
Rate-limit middleware can return a minimal body before a request ID is attached. Treat headers as the primary retry signal for 429.
Validation Errors
Structural validation can return 422 with:
- message set to Request validation failed
- description containing field paths and validation messages
Route-specific business validation can return 400 instead. Handle the status and documented operation schema rather than assuming every input problem is 422.
Idempotency Errors
Authenticated writes documented in OpenAPI accept an optional Idempotency-Key of at most 128 characters.
Idempotent requests can return:
- 400 for a key longer than 128 characters
- 409 with Retry-After: 1 when another request using the same key is still processing
- 503 with Retry-After: 1 when the replay guard cannot be established
The current OpenAPI standard response list does not enumerate 503, even though the idempotency guard can return it. Treat this as an operational response and retry the same request with the same key after the specified delay.
Successful idempotent responses can include:
- Idempotency-Status: created
- Idempotency-Status: replayed
- Idempotency-Status: waited
Retry Policy
Safe automatic retry candidates:
- GET after 429 or transient 5xx
- a documented write with the same Idempotency-Key after a connection failure, 429, or idempotency 503
Require review before retrying:
- an unkeyed write after an unknown network outcome
- a 409 caused by business state
- a 400 or 422
- a 401 or 403
Use exponential backoff with jitter and cap attempts. Preserve the original method, URL, query, payload, credential, and idempotency key for a replay.