Using the API
Errors
The JSON error body, and how idempotency failures use 409 and 422.
When the API returns an error body built for this contract, it has:
| Field | Meaning |
|---|---|
error_type | Machine-readable category. |
error_code | Same as error_type unless a more specific code is set. Branch on this when it is present. |
message | Human-readable text. |
status_code | HTTP status repeated in the body. |
field_errors | Present when validation failed on specific fields. |
There is no published catalogue of every error_code. Do not invent one. Read error_code when the body includes it, and otherwise use the HTTP status.
Statuses you will hit immediately
| Status | When |
|---|---|
| 401 | The token is missing, invalid, or for the other environment. |
| 409 | An idempotent POST is still in progress for that key. See Idempotency. |
| 422 | The same Idempotency-Key was sent with a different body. |
Other operations document their own status codes on the reference page. A 404 means the resource is missing or not visible to this token. Do not treat that as a signal to create the missing id yourself.
Do not retry a 422 by resending the same key and a new body. Generate a new key. For a 409 on an idempotent POST, retry the same request with the same key only after the first request has finished.