QEHSQEHS
Book a demo

Developer portal

API error codes

Every error response uses RFC 7807 Problem Details. The errorCode below is stable; deep-link directly into this page via the #anchor to explain a failure to your team.

Response shape

Every error from the QEHS API is application/problem+json with this shape:

{
  "type": "https://qehsethos.com/developers/errors#validation_failed",
  "title": "Validation failed",
  "status": 400,
  "errorCode": "validation_failed",
  "detail": "One or more fields are invalid.",
  "instance": "/api/v1/records",
  "traceId": "trace-abc-123",
  "errors": [
    { "path": "severity", "message": "Must be one of: high, medium, low", "code": "enum" }
  ]
}

Error classes

validation_failed

HTTP 400TERMINAL

Validation failed

Cause
One or more request fields failed validation (missing, wrong type, out of range).
How to resolve
Inspect the `errors[]` array for per-field feedback. Fix the offending fields and retry.

Example: `severity` must be one of: high, medium, low

unauthenticated

HTTP 401TERMINAL

Authentication required

Cause
No credentials supplied, or supplied credentials are invalid / expired.
How to resolve
Attach a valid API key, OAuth bearer token, or session cookie. Refresh the token if it has expired.

forbidden

HTTP 403TERMINAL

Forbidden

Cause
The authenticated principal lacks the required permission.
How to resolve
Request the permission from your tenant admin, or use a token that carries the needed scope.

not_found

HTTP 404TERMINAL

Resource not found

Cause
The resource does not exist, or the caller cannot see it (permission-aware).
How to resolve
Verify the ID. Confirm the resource belongs to your tenant.

conflict

HTTP 409CONDITIONAL

Conflict

Cause
The request conflicts with the current resource state (e.g. optimistic lock, duplicate key).
How to resolve
Reload the current state, reconcile your change against it, and retry. Conflicts on non-state-sensitive calls may be safe to retry immediately.

idempotency_key_conflict

HTTP 409TERMINAL

Idempotency-Key conflict

Cause
The supplied Idempotency-Key has been seen before with a different request body.
How to resolve
Generate a fresh Idempotency-Key for a new logical operation, or retry with the original body.

rate_limited

HTTP 429RETRYABLE

Rate limited

Cause
Your tenant or key exceeded the per-minute request quota.
How to resolve
Honour the `Retry-After` header. Published SDKs retry with exponential backoff automatically.

plan_limit_exceeded

HTTP 402TERMINAL

Plan limit exceeded

Cause
The action would exceed a limit on your current plan (users, modules, storage, API).
How to resolve
Upgrade the plan, or archive/delete existing resources to free capacity. `extensions.limit` names the exceeded limit.

feature_disabled

HTTP 403TERMINAL

Feature disabled

Cause
The requested feature is not enabled for your tenant on the current plan.
How to resolve
Upgrade the plan or contact sales. `extensions.featureKey` names the gate.

tenant_suspended

HTTP 403TERMINAL

Tenant suspended

Cause
The tenant has been administratively suspended (billing, abuse, compliance).
How to resolve
Contact support — the account needs human attention.

service_unavailable

HTTP 503RETRYABLE

Service temporarily unavailable

Cause
A downstream dependency is unreachable (DB, worker, external integration).
How to resolve
Retry with exponential backoff. Check `https://status.qehsethos.com` for any active incident.

internal_error

HTTP 500CONDITIONAL

Internal server error

Cause
Unexpected server failure. The `traceId` is captured in the error response.
How to resolve
Retry once with backoff. If the error persists, contact support with the `traceId` — it is enough to locate the failing request in our observability stack.