API Errors

Every failed request returns a status code and a detail field. Bindbee serves your reads from its synced copy, so a source system failing surfaces on the sync instead of here - see Find the source of an error.

Status codes

Status	Meaning	Retry?
`401`	Missing, malformed, or wrong-environment API key	No
`403`	Valid credentials without access to this resource	No
`404`	Resource doesn’t exist for this connector	No
`422`	Validation failed on a query parameter or write body	No
`429`	Rate limit exceeded	Yes, after `Retry-After`
`5xx`	Server-side	Yes, with backoff

Retrying a 4xx other than 429 never succeeds, and consumes the connector’s rate limit while failing. For what causes a 401 or a 403 specifically, see Authentication.

The response body

Every error carries a detail field, and its type depends on the status. On 401, 403, 404 and 429 it is a string. On 422 it is an array, one entry per rejected field:

{
  "detail": [
    {
      "loc": ["query", "page_size"],
      "msg": "Input should be less than or equal to 200",
      "type": "less_than_equal"
    }
  ]
}

The same key holds two types. Code that treats detail as a string works against every other status and throws on the first 422. Branch on the status before touching detail.

Retrying

On 429, wait the number of seconds in Retry-After - see Rate limits for the limit and the headers that track it. On 5xx, retry with exponential backoff and jitter, capped at a few attempts.

Retry a write only with X-Idempotency-Key. A 5xx can be returned after the record was created upstream - see Idempotency.

Authentication - what a 401 and a 403 mean for each header
Rate limits - the limit behind a 429, and the headers that track it
Idempotency - retrying a write without duplicating it
Find the source of an error - when the failure is on the sync rather than your request

Introduction

Core Concepts

Integrations

Use Cases

Status codes

The response body

Retrying

​Status codes

​The response body

​Retrying

​Related

Status codes

The response body

Retrying

Related