API docs
Sous Chef Management API
Request access

Errors and retries

Status codes

CodeMeaningRetry?
200Success. The body is the operation's reply object.n/a
400The request body failed validation.No. Fix the call.
401Missing, unknown or mismatched credentials.No. Fix the credentials.
403The key does not have the permission the operation needs.No. Contact support.
404An id in the request is unknown or is not your organization's.No. Fix the id.
409The request conflicts with the current state.No. Read the state.
422The request is valid but cannot be carried out as asked.No. Change the request.
429Over the rate limit. Limits apply per organization, not per key.Yes, after backing off.
5xxA fault on our side, or on a delivery platform's.Yes, with backoff.

404, 409 and 422 depend on the operation. Its page in the API Reference describes the cases.

Report a failure with its transaction id

A failure body carries statusCode, timestamp, path, method, a human-readable message, and txId, the identifier for that one call. Validate a request against the OpenAPI document before you send it: it lists every required field and accepted value.

Every operation in the API Reference uses the same ManagementApiError schema for its failures. A client generated from the OpenAPI document therefore gives you this body as a type.

{
  "statusCode": 401,
  "timestamp": "2026-09-04T14:07:22.113Z",
  "path": "/management/stores/fetchStores",
  "method": "POST",
  "message": "Unauthorized",
  "txId": "4f0a9c2e-6b31-4d77-9d0e-2a7f5c8b1e44"
}

The same value comes back on a response, failure or not, as the x-mealco-tx-id header. See Concepts → API conventions, which also explains how to send your own. Log it against every call, and quote it when you contact support so that we can find the complete record of that call.

A request whose body is not valid JSON has no id. It is rejected before it is processed, so that 400 carries a bare message and neither the fields above nor the header.

Retry policy

After a 429, wait 60 seconds and add jitter, unless the response carries Retry-After, in seconds, which you then honour. Rate limits are enforced before a request reaches the API. A 429 is a fixed response that carries neither the error body described above nor an x-mealco-tx-id. Treat a 429 with no headers and no JSON envelope as a rate limit all the same. Every limit is counted over a 60-second window, so a full window is enough to clear it.

Retry 429 and 5xx with exponential backoff and jitter. Start around one second, cap at a minute, and give up after a handful of attempts, then surface the failure. Do not retry 400, 401, 403, 404, 409 or 422: none becomes a different answer on a second attempt, and a tight retry loop on 401 can get the credential rate-limited as well.

Which calls are safe to repeat

Every read is safe to repeat. So is every write that sets a state you name: pausing and resuming stores, setting hours, setting item availability, revoking a promotion and updating webhook settings. Sending the same call twice leaves the same state as sending it once.

Three writes create something each time they succeed: createReport, createUberEatsPromotion and publishMenu. These three do not deduplicate retries, with or without an Idempotency-Key header. Before you retry one after a timeout, read back with fetchReports, fetchUberEatsPromotions or fetchMenuPublications to see whether the first call succeeded.

Do not parse messages

Branch on the status code and on documented fields. Human-readable messages can change without notice, and such a change is not a breaking change.