Skip to main content
Denialbase uses conventional HTTP status codes and a consistent error shape.

​
Status codes

CodeMeaningRetry?
200 OKRequest succeeded—
201 CreatedResource created—
204 No ContentSuccess, empty body—
301 / 302RedirectFollow
400 Bad RequestMalformed JSON or invalid request shapeNo — fix the request
401 UnauthorizedMissing or invalid authenticationRe-authenticate
402 Two-Factor RequiredComplete the 2FA stepComplete 2FA
403 ForbiddenAuthenticated but not authorizedNo — you lack permission
404 Not FoundResource doesn’t exist or is not visible to youNo
409 ConflictState conflict (e.g. duplicate, stale update)Refetch, reconcile
422 Unprocessable EntityValidation failedNo — fix the payload
429 Too Many RequestsRate limit hitYes — honor Retry-After
500 Internal Server ErrorUnexpected server errorYes — with backoff
502 / 503 / 504Transient infrastructure issueYes — 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

codeHTTPMeaning
not_authenticated401No valid session.
two_factor_required402Sign-in needs 2FA completion.
not_authorized403Pundit policy denied the action.
not_found404Resource doesn’t exist or isn’t visible.
validation_failed422One or more fields invalid. details populated.
rate_limited429Too many requests. Retry-After header set.
conflict409Concurrent modification; refetch and retry.
file_too_large413Upload exceeds 50 MB.
virus_detected422Uploaded file failed virus scan. Will not be processed.
internal_error500Our 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.