Sous Chef API
Sous Chef Onboarding API
Documentation

Errors and retries

The status-code table and retry policy on this page are copied verbatim from the Management API's docs/getting-started/03-errors-and-retries.md (ONE-2099), with exactly one adaptation: the 501 row's Retry column drops the twin's "watch the phase" pointer, because onboarding has no rollout-phases concept for a reader to watch — everything else in both sections, including the 501 row's Meaning cell, is identical to the twin. If you change anything here beyond that one cell, check the twin; if you change the twin, check here. The "Writes here are idempotent" section below is onboarding-specific and has no twin: Management API's Phase 0 surface is read-only, and this API's is not.

Status codes

CodeMeaningRetry?
200Success. The body is the operation's reply object.—
400The request body failed validation.No — fix the call.
401Missing, unknown or mismatched credentials.No — fix the credentials.
429Over the rate limit for this credential.Yes, after backing off.
501The operation's contract is published but its implementation has not shipped.No.
5xxA fault on our side.Yes, with backoff.

Retry policy

Retry 429 and 5xx with exponential backoff and jitter — start around one second, cap at a minute, give up after a handful of attempts and surface the failure rather than looping forever. Do not retry 400, 401 or 501: none of them becomes a different answer on a second attempt, and a tight retry loop on 401 is the fastest way to get a credential rate-limited as well.

Writes here are idempotent

Unlike a read-only API, a retry on this API can hit an operation that already wrote something — and it is still always safe. createLocation and addBrandsToLocation are both idempotent by construction: retrying either with the same input never creates a duplicate and never edits what the first call created. See Concepts → Retries and idempotency for exactly what makes that true, operation by operation.

This is also why there is no Idempotency-Key header anywhere on this API. The input itself is the deduplication key, so there is nothing an extra header would add.

Do not parse messages

Branch on the status code and on documented fields. Human-readable messages are for humans, and they change without notice — which is not a breaking change, because nothing promised them.