# API error codes

Source: https://docs.fiest.io/api/reference/errors

{/* This file was generated from x-fiest-error-codes. Do not edit it directly. */}

Fiest API errors use a stable machine-readable `error` code. Responses may
also include a safe `message` or `error_description`, plus a `request_id`
that you should include when contacting Fiest support.

For support, email [support@fiest.io](mailto:support@fiest.io) with the
`request_id`, API environment, endpoint, HTTP method, status code, and UTC
timestamp. Never send an access token, refresh token, authorization code,
cookie, or customer financial payload.

| Error code              | HTTP status | Retry automatically | Meaning                                                                                                                                               |
| ----------------------- | ----------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `authorization_expired` | 403         | No                  | The authenticated authorization no longer resolves an accessible restaurant. Ask the customer to authorize the integration again.                     |
| `capability_disabled`   | 503         | Yes                 | The capability is documented but is not enabled in the current Fiest environment.                                                                     |
| `conflict`              | 409         | No                  | The requested change conflicts with the current restaurant state or a platform limit.                                                                 |
| `idempotency_conflict`  | 409         | No                  | The supplied idempotency key was already used for a different request.                                                                                |
| `insufficient_scope`    | 403         | No                  | The access token does not include every scope required by the operation.                                                                              |
| `invalid_request`       | 400         | No                  | A path or query parameter is missing, malformed, or outside its supported bounds.                                                                     |
| `invalid_token`         | 401         | No                  | The bearer token, approved client, consent, membership, organization grant, or authorizer role is missing, expired, revoked, or invalid for this API. |
| `managed_externally`    | 409         | No                  | The requested setting is managed by an active external integration and cannot be changed through this API.                                            |
| `not_found`             | 404         | No                  | The resource does not exist or is outside the current authorization boundary.                                                                         |
| `payload_too_large`     | 413         | No                  | The JSON request body exceeds the documented size limit.                                                                                              |
| `precondition_failed`   | 409         | No                  | The restaurant state changed after it was reviewed. Fetch the latest state and build a new request.                                                   |
| `rate_limited`          | 429         | Yes                 | The partner request limit was exceeded. Wait for the Retry-After duration before retrying.                                                            |
| `service_unavailable`   | 503         | Yes                 | Fiest or a required downstream service is temporarily unavailable.                                                                                    |
| `write_in_progress`     | 409         | Yes                 | An idempotent write is still processing. Retry the exact request with the same idempotency key after Retry-After.                                     |

## Retry safely [#retry-safely]

* For `rate_limited`, wait for the response's `Retry-After` duration.
* For `service_unavailable`, use capped exponential backoff with jitter.
* For `write_in_progress`, wait for `Retry-After` and resend the exact
  request with the same idempotency key.
* For `precondition_failed`, fetch the latest state and build a new request;
  do not resend the stale request automatically.
* Do not repeatedly retry authorization, scope, validation, or not-found errors.
* A refreshed access token can resolve `invalid_token` when a valid rotating
  refresh token is available. Otherwise, ask the customer to reconnect.

Never parse the human-readable message for application logic. Match the
`error` value and retain the `request_id` for diagnostics.