Errors - Denialbase

Denialbase uses conventional HTTP status codes and a consistent error shape.

Status codes

Code	Meaning	Retry?
`200` OK	Request succeeded	—
`201` Created	Resource created	—
`204` No Content	Success, empty body	—
`301` / `302`	Redirect	Follow
`400` Bad Request	Malformed JSON or invalid request shape	No — fix the request
`401` Unauthorized	Missing or invalid authentication	Re-authenticate
`402` Two-Factor Required	Complete the 2FA step	Complete 2FA
`403` Forbidden	Authenticated but not authorized	No — you lack permission
`404` Not Found	Resource doesn’t exist or is not visible to you	No
`409` Conflict	State conflict (e.g. duplicate, stale update)	Refetch, reconcile
`422` Unprocessable Entity	Validation failed	No — fix the payload
`429` Too Many Requests	Rate limit hit	Yes — honor `Retry-After`
`500` Internal Server Error	Unexpected server error	Yes — with backoff
`502` / `503` / `504`	Transient infrastructure issue	Yes — with backoff

Error response shape

{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields failed validation.",
    "details": [
      { "field": "email", "message": "must be a valid email" },
      { "field": "denial_type", "message": "must be one of medical_necessity, prior_authorization, …" }
    ],
    "request_id": "req_01J9K7V5M3P8A2B1C6D4E7F9"
  }
}

code — stable machine-readable identifier. Safe to switch on.
message — human-readable, may change wording.
details — optional, present for validation-type errors.
request_id — include when reporting issues to support.

Common error codes

`code`	HTTP	Meaning
`not_authenticated`	401	No valid session.
`two_factor_required`	402	Sign-in needs 2FA completion.
`not_authorized`	403	Pundit policy denied the action.
`not_found`	404	Resource doesn’t exist or isn’t visible.
`validation_failed`	422	One or more fields invalid. `details` populated.
`rate_limited`	429	Too many requests. `Retry-After` header set.
`conflict`	409	Concurrent modification; refetch and retry.
`file_too_large`	413	Upload exceeds 50 MB.
`virus_detected`	422	Uploaded file failed virus scan. Will not be processed.
`internal_error`	500	Our bug. Please report with the `request_id`.

Retry strategy

Idempotent reads

GET requests can be retried freely. Use exponential backoff (starting at 500ms, capped at 30s) on transient errors.

Non-idempotent writes

POST / PUT / PATCH / DELETE — include an Idempotency-Key header (UUID). Denialbase will dedupe retries of the same key within a 24-hour window.

Idempotency example

curl -X POST https://api.denialbase.com/api/v1/documents \
  -H "Cookie: $SESSION_COOKIE" \
  -H "Idempotency-Key: 0f7c9e42-1a23-4b5c-9d0e-1234567890ab" \
  -F "file=@denial.pdf"

If the request times out and you retry with the same key, Denialbase returns the result of the original attempt — not a duplicate upload.

Reporting errors

When reporting an error to support, include:

The request_id from the error response (most useful).
The endpoint and method.
The approximate time (ISO 8601 with timezone).
What you expected to happen.

Email: support@denialbase.com.

​Status codes

​Error response shape

​Common error codes

​Retry strategy