Errors

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. For example, a customer can be saved before response validation fails. An idempotency key does not roll back that change or cache the failed response.

Behavior specification

Status Codes

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. It does not compare the body. Reusing a key with different content can replay the earlier result instead of applying the new content. Give each distinct operation a new key.

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
• 503 with Retry-After: 1 when Eigenn cannot set up the replay guard

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

Diagrams

Screenshots

Not applicable: this page describes an API or a non-visual workflow rather than an application screen.

Verification

1. Make a malformed request and confirm the client handles the returned 400 or 422 body, including absent optional fields.
2. Attempt to authenticate with invalid credentials and ensure a 401 status is returned.
3. Submit a request with a missing or insufficient scope and confirm a 403 response.
4. Test a missing ID on an operation that implements 404. Separately test malformed IDs and record route-specific validation or server errors.
5. On an isolated fixture and an operation with a valid success response, repeat the exact keyed write and check for the cached success with Idempotency-Status: replayed. Confirm only one persisted change. Exercise 409 and 503 separately by controlling concurrency and guard availability locally.
6. Exercise a local rate-limit fixture and verify 429 and Retry-After. Do not load-test a shared environment for this check.
7. 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.
8. Confirm that not all error responses contain every optional field, and that the client gracefully handles missing fields.

Related

Related Pages

• Authentication
• Rate Limits
• Developer API Setup