Skip to main content

​
Common headers

All authenticated endpoints require these headers.
HeaderRequiredDescription
AuthorizationAlwaysBearer <access_token> from /v1/auth/token/issue
Content-TypePOST onlyapplication/json
X-Idempotency-KeyPOST onlyUUID v4 used to prevent duplicate operations
Example 
Authorization: Bearer <YOUR_ACCESS_TOKEN>
Content-Type: application/json
X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

​
Idempotency

All POST requests must include an X-Idempotency-Key header with a valid UUID v4. This ensures retrying a request (for example, after a network timeout) does not create duplicate resources. Behavior
  • First request with a given key → processed normally
  • Subsequent requests with the same key → the original response is replayed without re-executing the operation
  • Keys are scoped per client and expire after 24 hours
  • Only successful responses (2xx) are cached
  • Failed requests can be retried with the same key
Replay header When a request is replayed, the response will include the following header so you can tell it apart from a fresh response: 
X-Idempotency-Replayed: true
Errors If the idempotency key is missing or invalid, the API will reject the request with one of the following errors:
  • 400 MISSING_IDEMPOTENCY_KEY — X-Idempotency-Key is required for POST requests
  • 400 INVALID_IDEMPOTENCY_KEY — X-Idempotency-Key must be a valid UUID

​
Common error responses

All error responses follow this format: 
{
  "success": false,
  "message": "Error description"
}
Authentication errors These apply to all authenticated endpoints:
  • 401 EMPTY_AUTH_KEY — Authentication token is required
  • 403 INVALID_AUTH_TOKEN — Authentication token is invalid or expired