Skip to content

Errors and status codes

The Public API follows standard HTTP status codes and documents the error body for each operation. Authentication failures can have an empty body. Use the status code to drive your retry and fallback logic.

Common status codes

  • 200 / 201: request successful.
  • 400: request is invalid (missing or malformed input).
  • 401: authentication error: an invalid, expired or revoked API key (the JWT sent in X-Api-Key), or a missing client or tenant header. A rejected API key returns an empty body and a WWW-Authenticate: ApiKey header.
  • 403: authorization error (no API key sent, or not allowed for the current tenant context).
  • 404: resource or requested page not found.
  • 409: the request conflicts with the current resource state or company configuration.
  • 429: rate limit exceeded (retry later).
  • 500: unexpected server error.

Error response shape

Error bodies depend on the failure source. Most JSON errors include a detail field describing what went wrong. Domain errors and rate-limit responses also include a stable code; validation and permission errors may instead include a status field or field-specific validation messages. Authentication can also return an empty body. The API Reference documents the possible bodies for each operation and status.

{
  "detail": "Rate limit exceeded",
  "code": "BSPORT-429"
}

A list request for a page that does not exist returns 404 with detail and a status field.

Shared infrastructure codes use the BSPORT-<http_status> pattern, for example BSPORT-429 for a rate-limit rejection and BSPORT-500 for an unexpected server error. Domain errors use exactly three uppercase letters followed by a hyphen and three digits, such as CLI-001, CAP-103, or ASV-001. When a response includes code, match on it rather than parsing detail: the message wording can change, while the documented code identifies the error.

Include the error code in support tickets

If you contact support, include the code value when present, the full response payload and the timestamp of the request to help us trace logs quickly.

Retries

  • Retry 429 responses after the rate limit window. See Rate limits and bulk data sync for the exact wait.
  • Do not retry 400 or 403 without changing the request.
  • Retry failed reads with bounded backoff. For writes, a 500, timeout or lost response does not prove that no change occurred. Read the affected resource before deciding whether to retry. Communication sends cannot be conclusively matched after a lost response and must not be automatically resent.
  • For a configuration conflict, correct the company or resource configuration before retrying. Gift-card and product financial setup is not editable through this API; arrange that setup with the company in Back Office.

No Retry-After header is returned

A 429 response carries the standard error body and no Retry-After header. Wait for the documented rate limit window rather than reading a header value.