Errors and retries
Status codes
| Code | Meaning | Retry? |
|---|---|---|
200 | Success. The body is the operation's reply object. | n/a |
400 | The request cannot be carried out as sent. | No. Fix the call. |
401 | Missing, unknown, revoked or mismatched credentials. | No. Fix the credentials. |
403 | The key is valid but is not permitted to use this API. | No. Contact support. |
429 | Over the rate limit for your organization. | Yes, after backing off. |
5xx | A fault on our side. | Yes, with backoff. |
A 400 covers a field that failed validation, a locationId that is not one of your organization's, and a location code that is already in use.
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 403: none becomes a different answer on a second attempt, and a tight retry loop on 401 can get the credential rate-limited as well.
Send one call for a location at a time. Wait for the answer to createLocation before you send it again, and do not send two identical calls in parallel.
Writes here are idempotent
A retry on this API can reach an operation that has already written something. It is still safe. createLocation and addBrandsToLocation are both idempotent: retrying either with the same input never creates a duplicate and never edits what the first call created. See Concepts → Retries and idempotency for the behaviour of each operation.
This is also why this API has no Idempotency-Key header. The input itself is the deduplication key, so an extra header would add nothing.
Do not parse messages
Branch on the status code and on documented fields. Human-readable messages are meant for people and can change without notice. A change to a message is not a breaking change.