Join now

Discount for all plans 40%

Join Now
BUILD IT
HomePricing

API errors

Every error returns application/problem+json with a stable error.code and an error.request_id that matches the X-Request-Id response header. The fragment #errors-<code> on this page is the canonical URL referenced by error.doc_url.

Envelope

{
  "error": {
    "code": "<see table>",
    "type": "https://buildgazette.com/developers/errors#errors-<code>",
    "title": "<human title>",
    "status": <http-status>,
    "message": "<actionable detail>",
    "doc_url": "https://buildgazette.com/developers/errors#errors-<code>",
    "request_id": "<uuid>"
  }
}
missing_api_key
HTTP 401
link

When: The request did not include an Authorization header.

Fix: Add `Authorization: Bearer <bi_...>` (case-sensitive scheme).

invalid_api_key
HTTP 401
link

When: The key is malformed, unknown, or revoked.

Fix: Mint a fresh key at /account. If you just rotated, the old key revokes in 24h (or instantly with `?immediate=true`).

origin_not_allowed
HTTP 403
link

When: The browser `Origin` header is not in the per-key allowlist.

Fix: Add the origin to the key in /account, or call from a server (no Origin header is permitted).

ip_not_allowed
HTTP 403
link

When: The caller IP is not in the per-key allowlist (supports IPv4 CIDR).

Fix: Whitelist the IP or CIDR block in /account, or remove the allowlist if you call from variable IPs.

insufficient_scope
HTTP 403
link

When: The key does not hold any of the scopes required by the endpoint.

Fix: Re-issue the key with the necessary scope(s) — see the Scopes section on the main docs page.

rate_limited
HTTP 429
link

When: 60 requests in the past 60 seconds for this key.

Fix: Back off — `Retry-After` says how long. Watch `X-RateLimit-Remaining` to avoid 429s entirely.

daily_quota_exceeded
HTTP 429
link

When: The key reached its `daily_call_limit` for the UTC day.

Fix: Raise the limit on the key in /account (Plus+) or wait until 00:00 UTC.

invalid_query
HTTP 400
link

When: A required query parameter is missing or fails validation (e.g. `q` < 2 chars on /search).

Fix: Read the `message` field — it names the bad parameter.

not_found
HTTP 404
link

When: The slug or username does not exist, or the resource is unpublished.

Fix: Double-check the path segment. Listing endpoints return only published items, so a private draft will look like a 404.

query_failed
HTTP 500
link

When: An internal database call failed.

Fix: Retry with exponential backoff. If it persists, send the `request_id` (in `X-Request-Id`) to support.

internal_error
HTTP 500
link

When: Unexpected exception inside the handler.

Fix: Quote `X-Request-Id` when contacting support — we can find the matching log line in seconds.

Retries

Retry 5xx with exponential backoff. Do not retry 4xx — they will return the same error. Use Idempotency-Key on non-GET writes to ensure exactly-once semantics if you do retry. The keys 11 listed above are the complete catalog; anything else indicates the spec is out of date — please file an issue.