Errors

A refused call answers a 4xx or 5xx status with an RFC 9457 problem document, Content-Type: application/problem+json:

{
  "type": "https://hub.masjidbox.com/docs/errors/MASJID_NOT_FOUND",
  "title": "Masjid not found",
  "status": 404,
  "detail": "No such masjid.",
  "instance": "/v1/masjids/msj_abc123defg",
  "code": "MASJID_NOT_FOUND",
  "requestId": "req_8f14e45fceea167a5a36dedd4bea2543",
  "requestLogUrl": "https://hub.masjidbox.com/console/logs/req_8f14e45fceea167a5a36dedd4bea2543"
}

Switch on code

code is stable: write your error handling against it. title is stable too, but meant for people. detail describes this one occurrence and may change at any time: show it, log it, never branch on it.

type is the page that explains the code, and status repeats the HTTP status.

The links in a refusal

• requestLogUrl: this request in your own request log. It is absent when no key was recognised, since the request then belongs to no project.
• quotaIncreaseUrl: on PROJECT_QUOTA_EXCEEDED only, the form that asks for a higher quota for this project.

Retry or not

• 400, 401 and 404 will not change on a retry: fix the call first.
• 429 carries Retry-After: wait that many seconds.
• 500 may pass on a retry. Back off, and quote the requestId if it persists.

Every code has its own page, with why it happens and what to do.