Errors

Every error is an RFC 9457 problem document, sent as application/problem+json:

{
  "type": "https://docs.dialerbee.com/errors/insufficient-scope",
  "title": "Not permitted",
  "status": 403,
  "detail": "The API client does not hold the scope this operation requires.",
  "instance": "urn:dialerbee:request:req_01K6BZ3M9X4T7Q2V8N5R6P1W0C",
  "code": "insufficient_scope",
  "request_id": "req_01K6BZ3M9X4T7Q2V8N5R6P1W0C"
}

Rules

• Branch on the HTTP status and code, never on detail or title text.
• New codes can be added inside v1. Treat an unknown code by its HTTP status.
• Every 429 and 503 carries Retry-After in seconds. Wait at least that long.
• A 409 outcome_unknown means the platform could not confirm whether a write happened: never retry it with a new Idempotency-Key. See Idempotency.
• Unknown paths answer 404 route_not_available; a known path with another method answers 405 method_not_allowed with an Allow header.
• Every response, error or not, carries an X-Request-ID. It is req_ and a ULID when the API answered, for example req_01K6BZ3M9X4T7Q2V8N5R6P1W0C, or edge_ and 32 hexadecimal characters when the edge answered before the request reached the API (an unknown route, a body that is too large, the per-address rate limit, or the API unavailable), for example edge_7c1e9a3f5b2d4c6e8a0f1b3d5e7c9a2b.

Every code

Authentication

Access

Request

Validation

Idempotency

Resource

State

Compliance

Capacity

Concurrency

Server