API error codes
Stable error codes, retry guidance, and support correlation IDs.
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 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
- For
rate_limited, wait for the response'sRetry-Afterduration. - For
service_unavailable, use capped exponential backoff with jitter. - For
write_in_progress, wait forRetry-Afterand 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_tokenwhen 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.