Errors
Every error has the same shape, whatever the route:
{
"error": "code_not_found",
"message": "The code does not exist for this partner.",
"requestId": "01J9Q6X0Z8N4C5R7T2V9W3Y1B0"
}
erroris a stable, machine-readable code. Build your logic on it, together with the HTTP status.messageis an English explanation for developers. It can change; never parse it.requestIdis the id of the call, identical to theX-Request-Idresponse header. Log it, and include it when you contact us.
Successful responses are plain objects; they are never wrapped in a success envelope.
Error codes
| Status | error | Meaning | What to do |
|---|---|---|---|
| 400 | validation_error | The request is malformed or a field is invalid. message says which. | Fix the request. Do not retry unchanged. |
| 401 | invalid_client | Token request only: the client id or secret is missing or wrong, the client is inactive, or it belongs to the other environment. | Check the credentials and the host. |
| 401 | invalid_token | The access token is missing, expired, invalid, or issued for the other environment. | Get a new token and retry once. |
| 403 | insufficient_scope | The token does not grant the scope the operation requires. | Add the scope to the client, then get a new token. |
| 403 | ip_not_allowed | The call comes from an address outside the client's IP allowlist. | See IP allowlist. |
| 403 | certificate_required | The client has client certificates registered, and the request did not present one. | See Client certificates (mTLS). |
| 403 | certificate_not_allowed | The client certificate presented is not registered for the client. | See Client certificates (mTLS). |
| 403 | forbidden | Token request only: the request was refused for a reason not covered by another code. | Contact B2B Group with the requestId. |
| 404 | code_not_found | The code does not exist for your account in this environment. | |
| 404 | not_found | The route, webhook endpoint, delivery or order does not exist. | |
| 409 | code_already_used | The code has already been used. | |
| 400 | code_expired | The code has expired. | |
| 400 | code_deactivated | The code has been deactivated. | |
| 400 | insufficient_tier | The tiers of the codes used together do not add up to the tier of the selected gift. | Use codes with a higher tier, or choose another gift. See Codes. |
| 409 | delivery_not_retryable | Only a failed or abandoned webhook delivery can be retried. | |
| 409 | sandbox_shop_missing | Sandbox only: no sandbox shop is set up for your account yet. | Contact B2B Group. |
| 429 | rate_limited | Too many requests. | Wait the number of seconds in Retry-After, then retry. |
| 502 | upstream_error | The request could not be completed right now. | Retry later with backoff. |
New error codes can be added within a contract version. Handle an unknown error by its HTTP status.
Retrying safely
- Retry
429afterRetry-After, and502with increasing waits (for example 1, 5 and 30 seconds). - Retry
401 invalid_tokenonce, after fetching a new token. - Do not retry other
4xxerrors unchanged; they will fail the same way. - Imports and deactivations are idempotent, so repeating them after a timeout is safe. Repeating
POST /v1/codes/issueafter a timeout can issue a second code. Before issuing again, list the codes changed in the last minutes withGET /v1/codes?updatedSince=...and match onexternalMemberRef.
Rate limits
| Limit | Applies to |
|---|---|
| 600 requests per minute per client | /v1/codes, /v1/webhook-endpoints and /v1/sandbox routes |
| 30 requests per minute per IP address | POST /v1/oauth/token |
The window slides, so a burst at the end of one minute and the start of the next does not double the
limit. Above the limit the API answers 429 rate_limited with Retry-After in whole seconds. The
sandbox has the same limits as production.