Skip to content
B2B GroupPartner API

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"
}
  • error is a stable, machine-readable code. Build your logic on it, together with the HTTP status.
  • message is an English explanation for developers. It can change; never parse it.
  • requestId is the id of the call, identical to the X-Request-Id response 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

StatuserrorMeaningWhat to do
400validation_errorThe request is malformed or a field is invalid. message says which.Fix the request. Do not retry unchanged.
401invalid_clientToken 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.
401invalid_tokenThe access token is missing, expired, invalid, or issued for the other environment.Get a new token and retry once.
403insufficient_scopeThe token does not grant the scope the operation requires.Add the scope to the client, then get a new token.
403ip_not_allowedThe call comes from an address outside the client's IP allowlist.See IP allowlist.
403certificate_requiredThe client has client certificates registered, and the request did not present one.See Client certificates (mTLS).
403certificate_not_allowedThe client certificate presented is not registered for the client.See Client certificates (mTLS).
403forbiddenToken request only: the request was refused for a reason not covered by another code.Contact B2B Group with the requestId.
404code_not_foundThe code does not exist for your account in this environment.
404not_foundThe route, webhook endpoint, delivery or order does not exist.
409code_already_usedThe code has already been used.
400code_expiredThe code has expired.
400code_deactivatedThe code has been deactivated.
400insufficient_tierThe 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.
409delivery_not_retryableOnly a failed or abandoned webhook delivery can be retried.
409sandbox_shop_missingSandbox only: no sandbox shop is set up for your account yet.Contact B2B Group.
429rate_limitedToo many requests.Wait the number of seconds in Retry-After, then retry.
502upstream_errorThe 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 429 after Retry-After, and 502 with increasing waits (for example 1, 5 and 30 seconds).
  • Retry 401 invalid_token once, after fetching a new token.
  • Do not retry other 4xx errors unchanged; they will fail the same way.
  • Imports and deactivations are idempotent, so repeating them after a timeout is safe. Repeating POST /v1/codes/issue after a timeout can issue a second code. Before issuing again, list the codes changed in the last minutes with GET /v1/codes?updatedSince=... and match on externalMemberRef.

Rate limits

LimitApplies to
600 requests per minute per client/v1/codes, /v1/webhook-endpoints and /v1/sandbox routes
30 requests per minute per IP addressPOST /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.