Error Handling

ClaimRev's API uses standard HTTP status codes. The shape of the response body on errors depends on the endpoint and is documented per-endpoint in the API Reference.

HTTP status codes

Code	Meaning	Recoverable?
200	OK	n/a
400	Bad Request — request was malformed or failed validation. The body usually identifies the problem.	No, fix the request
401	Unauthorized — token is missing, malformed, expired, or for the wrong environment.	Yes, request a new token
403	Forbidden — token is valid, but your client isn't authorized for this endpoint or this account.	No, contact support if you believe access should be granted
404	Not Found — the resource doesn't exist (or isn't visible to your account).	No
500	Internal Server Error — something on ClaimRev's side broke.	Sometimes, with backoff

Most read endpoints return 200 with a typed payload on success. Validation failures generally return 400 with a payload that names the failing field; semantic failures (e.g., trying to delete a record that doesn't exist) generally return 404.

Authentication errors

Token-endpoint errors come from Azure B2C, not ClaimRev. The full error catalog is in Microsoft's B2C error reference. The most common shapes:

• invalid_client — wrong client_id or client_secret
• invalid_scope — the scope parameter doesn't match the environment's expected scope
• invalid_grant — grant_type or other parameters are malformed

API-side 401 means your token didn't authenticate against the API. This is almost always one of:

• Token expired (request a new one — they live for an hour)
• Token from the wrong environment (test token against prod API or vice versa)
• Token missing from the Authorization header

API-side 403 means the token authenticated but your client isn't authorized for the call. The common causes:

• Your client id isn't bound to the account number you're targeting
• The endpoint requires a permission your client hasn't been granted

Retrying

Retry on transient failures with exponential backoff:

1st retry: 1 second
2nd retry: 2 seconds
3rd retry: 4 seconds
4th retry: 8 seconds
Give up after 5 attempts and surface the error.

Add a small random jitter (e.g., 0–500ms) so simultaneous failures don't synchronize their retries.

Don't retry on: 400, 401 (without first refreshing the token), 403, 404. These are deterministic given the current inputs — retrying without changing something will just produce the same error.

Logging

When errors are unrecoverable in your code, capture and log:

• The HTTP method, path, and (sanitized) request body
• The HTTP status code and full response body
• A timestamp

If you escalate an issue to ClaimRev support, the response body and the timestamp are usually enough for support to find the corresponding server-side log.

When to contact support

• Repeated 5xx errors after backoff retries are exhausted
• 4xx errors where the response body doesn't match what you're sending
• Claims that disappeared between submission and search results
• Eligibility/claim-status responses that don't seem consistent with payer reality

Reach out through your account manager or the portal's support channel with the timestamp and the response body.

A note on what isn't here yet. Today's API does not enforce per-client rate limits, doesn't honor idempotency keys, doesn't return a structured traceId, and the error response shape isn't fully consistent across endpoints. These are known gaps — under consideration for a future API v2 — not behaviors to rely on. If consistent error handling matters for your integration, build defensively: log the raw HTTP code and full response body, treat unfamiliar shapes as opaque, and surface them upward.