Errors

Every error has the same JSON body:

{
  "code": "QUOTE_EXPIRED",
  "message": "The quote has expired.",
  "detail": { "reason": "geography_changed" },
  "request_id": "req_01JC9W6Q4V5Y8Z2M3N4P5R6S7T"
}

• code is stable. Write your logic against it.
• message is for your developers and logs. Do not show it to customers; map the code to your own words, or use the customer wording in the error code reference.
• detail is optional and adds a field, a reason or other facts named in the reference.
• request_id is also in the X-Request-Id header. Give it to support and they can find exactly what happened.

A 500 INTERNAL_ERROR carries only the request ID. IDM never puts internal details in an error.

What to do, by kind

Kind	Codes (examples)	What your code does
Fix the request	VALIDATION_FAILED, SERVER_CONTROLLED_FIELD, IDEMPOTENCY_KEY_REQUIRED	Do not retry. Fix the request.
Fix the credential	INVALID_API_CREDENTIAL, SIGNATURE_INVALID, SCOPE_MISSING	Do not retry. Check the key, the clock, the signature or the scopes.
Not yours, or not there	TENANT_ACCESS_DENIED, NOT_FOUND	Do not retry. Check the reference.
The world changed	QUOTE_EXPIRED, INVALID_DELIVERY_STATE, BULK_QUOTE_CHANGED, DELIVERY_ALREADY_ASSIGNED	Read the resource again, then decide. A new quote is usually the answer.
Duplicate	IDEMPOTENCY_KEY_REUSED, EXTERNAL_REFERENCE_IN_USE, DUPLICATE_JOB_INTENT	You sent a different request under an old key or reference. Look up the original.
Not possible here	LOCATION_NOT_SUPPORTED, VEHICLE_UNAVAILABLE, NO_ELIGIBLE_PARTNER, PARTNER_BLOCKED, MODULE_DISABLED	Tell the customer, offer another option.
Wait and retry	REQUEST_IN_FLIGHT, RATE_LIMIT_EXCEEDED, RETRYABLE, ROUTING_UNAVAILABLE, PRICING_UNAVAILABLE, REQUEST_TIMEOUT, any 5xx	Retry with backoff and the same idempotency key. Honour Retry-After.

The error code reference lists every code with its HTTP status, what it means and what to do. It is generated from the server's own error catalogue.

HTTP status codes

Status	Meaning
200 / 201 / 202	Success (202: accepted, carried out shortly)
400	The request is malformed or invalid
401	Authentication failed
403	Not allowed, or not your resource
404	No such route
409	Conflict with current state, or an idempotency conflict
410	A link has expired
413	The body is too large
422	The request contains a field only the server may set
429	Too many requests
500	Something went wrong at IDM; the request ID tells support what
503	Temporarily unavailable; retry