Errors

One shape for every failure, a stable code, and what to do about each status.

Every failure comes back in the same shape. code is stable and is what your software should branch on; message is written for a person reading a log.

Any error

{
  "error": {
    "code": "not_found",
    "message": "No credential with id cred_… in this organization.",
    "details": { }
  }
}

Status	Typical code	What it means
`400`	a specific code	The body did not validate, or the request does not make sense for this resource. `details` says what.
`401`	`unauthorized`	Missing or invalid credentials. Check the `Authorization` header.
`403`	`forbidden`	Authenticated, but this key may not do that. Not a retry.
`404`	`not_found`	No such resource in this organisation — which is also the answer for something that belongs to another.
`409`	a specific code	A conflict: a duplicate key, a subject who still holds credentials, or an idempotent request still running.
`503`	`unavailable`	Something behind that endpoint is not configured or not answering. Retry later.

What to retry

Retry 5xx, with backoff, and with the same Idempotency-Key you used the first time.
Do not retry 400, 403 and 404 — the same request will fail the same way.
409 on an idempotent request means the first attempt is still running. Wait, then retry with the same key.

Webhooks

Being told instead of asking.

Best practices

A well-behaved integration.