Errors
Interpret Eigenn API statuses, optional error fields, request IDs, and safe retry signals.
Summary
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"
}Do not make a client fail to parse an error when one of these fields is absent.
Capabilities
Clients can interpret and respond to a consistent set of HTTP status codes, retrieve and log request identifiers for troubleshooting, handle validation and idempotency errors, and apply safe retry logic as guided by the API's conventions.
Prerequisites
You must have access to Eigenn's public REST API endpoints and valid API credentials. To handle idempotency and retry patterns, your client implementation should support reading response headers and preserving request context.
Concepts
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 a sensitive customer payload to keep debug context.
Rate-limit responses can contain only an error field in the body. The API adds X-Request-ID through its outer middleware; body requestId is not guaranteed. Read Retry-After from the response headers for 429.
Workflow
Retry Policy
Use bounded retries for:
- GET after 429 or transient 5xx
- a rate-limited request after Retry-After
- an idempotency-guard 503, preserving the same request and key after Retry-After
Examine these cases before you retry:
- any write after an unknown network outcome or a server error, even with an idempotency key
- a 409 caused by business state
- a 400 or 422
- a 401 or 403
Use exponential backoff with jitter. Limit the number of tries. Preserve the original method, URL, query, payload, credential, and idempotency key for a replay.
A failed write response does not prove that no change occurred. Check the resource or application before retrying. An idempotency key does not roll back that change or cache the failed response.
Behavior specification
Status Codes
| Status | Description | Typical action |
|---|---|---|
| 400 | Missing, malformed, or semantically invalid request | Correct the request before you retry it. |
| 401 | Missing or invalid authentication | Replace or refresh the credential. |
| 402 | Billing blocks the requested write (BILLING_WRITE_BLOCKED) | Restore writable billing before retrying; new credentials do not remove this gate. |
| 403 | Credential lacks permission, including scopes removed by the user's current role | Check the grant and current team role. |
| 404 | Resource missing or inaccessible to the team | Check the ID and the team. |
| 409 | Conflict with current state or an in-flight idempotent request | Examine the state and Retry-After when present. |
| 422 | Request validation failed or an idempotency key was reused with a changed body | Correct invalid fields, or use a new key for a genuinely new operation. |
| 429 | Rate limit exceeded | Wait for Retry-After. |
| 500 | Unexpected server error | Retry a safe operation with backoff. |
| 503 | Idempotency guard unavailable | Preserve the request and key; wait for Retry-After. |
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.
Validation Errors
Structural validation can return 422 with:
- message set to Request validation failed
- description with field paths and validation messages
Route-level request validation can instead return 400 with a validation result object. Business validation can also return 400. Handle the status and body defensively; do not require the normalized description field or assume every input problem is 422. Likewise, a missing or malformed resource ID does not guarantee 404: some routes currently surface a server or response-validation error.
Idempotency Errors
Protected POST, PUT, PATCH, and DELETE requests accept an optional Idempotency-Key of at most 128 characters after trimming. An empty value is treated as no key.
The guard stores successful 2xx responses for 24 hours. Replay identity includes the team and authenticated user or service principal, HTTP method, path, query string, and key. For current cached responses, the guard compares a hash of the exact request body and returns 422 if it differs; even JSON whitespace or field order can matter. Older cache entries without a body hash can still replay their original response. Use one key for one unchanged request.
Non-2xx results are not cached. A successful write can also outlive a cache failure, so replay is not an exactly-once guarantee. After an uncertain write, reconcile persisted state before deciding whether to repeat it.
Idempotent requests can return:
- 400 for a key longer than 128 characters
- 409 with Retry-After: 1 when another request with the same key is still in progress
- 422 when the stored request-body hash differs
- 503 with Retry-After: 1 when Eigenn cannot set up the replay guard
The current OpenAPI standard response list does not enumerate billing 402 or idempotency 503, even though the relevant middleware can return them. For 503, retry the same request with the same key after Retry-After. For 402, restore billing write access first.
Successful idempotent responses can include:
- Idempotency-Status: created
- Idempotency-Status: replayed
- Idempotency-Status: waited
Diagrams
Rendering diagram…
Screenshots
Not applicable: this page describes an API or a non-visual workflow rather than an application screen.
Verification
- Make a malformed request and confirm the client handles the returned 400 or 422 body, including absent optional fields.
- Attempt to authenticate with invalid credentials and ensure a 401 status is returned.
- Submit a request with a missing or insufficient scope and confirm a 403 response.
- Test a missing ID on an operation that implements 404. Separately test malformed IDs and record route-specific validation or server errors.
- On an isolated fixture, repeat the exact successful keyed write and check Idempotency-Status: replayed and one persisted change. Change the body with the same key and confirm 422 for a current cache entry. Exercise legacy unhashed replay, in-flight 409, unavailable-guard 503 and billing 402 separately.
- Exercise a local rate-limit fixture and verify 429 and Retry-After. Do not load-test a shared environment for this check.
- Simulate an uncertain write response and confirm the client reconciles state instead of retrying blindly. Check that secrets and customer payloads are absent from logs.
- Confirm that not all error responses contain every optional field, and that the client gracefully handles missing fields.