Errors

Every error follows the same shape:

{
  "error": {
    "type": "insufficient_scope",
    "message": "This key can't write to inventory.",
    "request_id": "req_01HRTX6S5ZJC7CN9FN2YTKE5X9",
    "fix": "Add inventory:write to the key in Dashboard → Settings → API keys.",
    "docs": "https://dib.io/developers/errors#insufficient_scope"
  }
}

Always log request_id on failures — Dib support can replay any request given that ID.

Catalog

Type	Status	Meaning
authentication_required	401	Missing or malformed Authorization header.
invalid_api_key	401	Key doesn't exist, was revoked, or has a bad checksum.
pro_required	402	Team isn't on Pro (or grace period ended). Upgrade to continue.
insufficient_scope	403	Key is missing the scope required for this endpoint.
ip_not_allowed	403	Caller IP is outside the key allowlist.
not_found	404	Resource is missing or belongs to a different team.
method_not_allowed	405	Endpoint exists but not for this HTTP method.
conflict	409	Idempotency replay with a mismatched payload.
validation_error	422	Body did not satisfy the endpoint schema.
rate_limited	429	Slow down. Retry after Retry-After seconds.
quota_exhausted	429	Team-wide quota (AI minutes, monthly requests) used up.
internal_error	500	Dib bug. Reach out with the request_id.
upstream_unavailable	502	A dependency (AI, storage) is down. Retry with backoff.

Retry policy

Retry 429, 502, and 503with exponential backoff and full jitter. Don't retry 4xxotherwise — the request is still going to fail.

Errors

Every error follows the same shape:

{
  "error": {
    "type": "insufficient_scope",
    "message": "This key can't write to inventory.",
    "request_id": "req_01HRTX6S5ZJC7CN9FN2YTKE5X9",
    "fix": "Add inventory:write to the key in Dashboard → Settings → API keys.",
    "docs": "https://dib.io/developers/errors#insufficient_scope"
  }
}

Always log request_id on failures — Dib support can replay any request given that ID.

Catalog

Type	Status	Meaning
authentication_required	401	Missing or malformed Authorization header.
invalid_api_key	401	Key doesn't exist, was revoked, or has a bad checksum.
pro_required	402	Team isn't on Pro (or grace period ended). Upgrade to continue.
insufficient_scope	403	Key is missing the scope required for this endpoint.
ip_not_allowed	403	Caller IP is outside the key allowlist.
not_found	404	Resource is missing or belongs to a different team.
method_not_allowed	405	Endpoint exists but not for this HTTP method.
conflict	409	Idempotency replay with a mismatched payload.
validation_error	422	Body did not satisfy the endpoint schema.
rate_limited	429	Slow down. Retry after Retry-After seconds.
quota_exhausted	429	Team-wide quota (AI minutes, monthly requests) used up.
internal_error	500	Dib bug. Reach out with the request_id.
upstream_unavailable	502	A dependency (AI, storage) is down. Retry with backoff.

Retry policy

Retry 429, 502, and 503with exponential backoff and full jitter. Don't retry 4xxotherwise — the request is still going to fail.