> ## Documentation Index
> Fetch the complete documentation index at: https://docs.osaconnection.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Errors
> Error format, the stable error codes, and what to do about each one.
Errors use [RFC 9457 problem details](https://www.rfc-editor.org/rfc/rfc9457) with the content type `application/problem+json`:
```json theme={"system"}
{
"type": "https://docs.osaconnection.com/errors#duplicate_claim",
"title": "Duplicate claim",
"status": 409,
"detail": "Your firm already has a claim with external_id CMS-884512.",
"code": "duplicate_claim",
"request_id": "3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b",
"existing_claim_id": "3f8a2c61-5b7e-4d2a-9c1e-7a4b2d9e6f10",
"existing_claim_url": "https://api.osaconnection.com/v1/claims/3f8a2c61-5b7e-4d2a-9c1e-7a4b2d9e6f10"
}
```
| Field | Meaning |
| - | - |
| `code` | **The stable error code. Match on this.** |
| `status` | The HTTP status code. |
| `title`, `detail` | Human-readable explanation. Wording may change; don't parse it. |
| `type` | A link to this page's entry for the code. |
| `request_id` | The request's id. Quote it when you contact [OSA support](/introduction#support). It is the same value as the `X-Request-Id` response header, which every response carries, successful ones included. |
| `errors` | For `validation_failed`: each problem, with `detail` saying what is wrong and one of `pointer` (a JSON Pointer to a body field, such as `/loss/date`), `parameter` (a query or path parameter, such as `limit`) or `header` (such as `Idempotency-Key`). |
| `existing_claim_id`, `existing_claim_url` | For `duplicate_claim`: the claim that already exists. Always a claim your key can read. |
New codes may be added. Treat an unknown code by its HTTP status.
## Error codes
| Code | Status | Meaning |
| - | - | - |
| [`malformed_request`](#malformed_request) | 400 | The body isn't valid JSON or can't be read |
| [`invalid_key`](#invalid_key) | 401 | The key is missing, malformed, unknown, revoked or expired |
| [`insufficient_scope`](#insufficient_scope) | 403 | The key's purpose doesn't include this permission |
| [`not_in_plan`](#not_in_plan) | 403 | Your firm's plan doesn't include this |
| [`not_found`](#not_found) | 404 | Nothing with this id exists in your firm, or your key can't see it |
| [`duplicate_claim`](#duplicate_claim) | 409 | The claim already exists |
| [`claim_already_accepted`](#claim_already_accepted) | 409 | An accepted claim can't be offered to another adjuster |
| [`already_member`](#already_member) | 409 | The adjuster is already a member of your firm |
| [`invitation_pending`](#invitation_pending) | 409 | The adjuster already has a pending invitation |
| [`payload_too_large`](#payload_too_large) | 413 | The body is larger than 1 MB |
| [`validation_failed`](#validation_failed) | 422 | The request is invalid |
| [`idempotency_key_reused`](#idempotency_key_reused) | 422 | The `Idempotency-Key` was used with a different request |
| [`unknown_osaid`](#unknown_osaid) | 422 | No OSA user has this OSAID |
| [`adjuster_not_in_firm`](#adjuster_not_in_firm) | 422 | The adjuster isn't an active member of your firm |
| [`adjuster_not_accepting`](#adjuster_not_accepting) | 422 | The adjuster can't take claims right now |
| [`environment_mismatch`](#environment_mismatch) | 422 | A live key named a test account (in a claim or an invitation), or tried to offer a test claim |
| [`rate_limited`](#rate_limited) | 429 | Too many requests for this key |
| [`internal_error`](#internal_error) | 500 | Something failed on OSA's side |
The body isn't valid JSON, or couldn't be read. Check that you send `Content-Type: application/json` and a complete JSON document.
invalid\_key
Check the `Authorization: Bearer …` header and that the key hasn't been revoked. If it was rotated, use the new key.
insufficient\_scope
The key works but wasn't issued for this operation. `GET /v1/me` lists its permissions. Use a key issued for this purpose, or ask OSA to change it.
not\_in\_plan
Your firm's plan doesn't include this capability. Contact OSA about your plan.
not\_found
The id doesn't exist in your firm. Another firm's claim, and a real claim requested with a test key, also return this. For `DELETE /v1/adjusters/invitations/{osa_id}`, it means there is no pending invitation for that OSAID.
duplicate\_claim
In the key's environment, your firm already has a claim with this `external_id`, or an open claim sent through the API with this `claim_number`. Test and live claims are checked separately and never collide. `existing_claim_id` and `existing_claim_url` always point to a claim your key can read: use it instead of creating a new claim.
claim\_already\_accepted
The adjuster accepted the claim, so it can't be offered to someone else. Reassigning accepted claims isn't supported yet.
already\_member
The adjuster has already accepted an invitation to your firm. There is nothing to invite or withdraw.
invitation\_pending
You already invited this adjuster and they haven't answered. Ask them to open the OSA app, or withdraw the invitation and send a new one.
payload\_too\_large
Request bodies are limited to 1 MB. Files never go through the API.
validation\_failed
The request doesn't match the API reference: a missing or unknown body field, an unknown query parameter, a wrong type or format, leading or trailing spaces in `external_id` or `claim_number`, or a missing `Idempotency-Key` header. `errors` lists each problem.
It also covers the two rules that compare one field with another when you send a claim:
* a `building.building_type` that doesn't go with `building.occupancy_type`, or that isn't a residential type when no occupancy type is sent. The `pointer` is `/building/building_type`. See [Occupancy and building type](/occupancy-and-building-type).
* a `policy.expiration_date` earlier than `policy.effective_date`. The `pointer` is `/policy/expiration_date`. See [Claim details](/claim-details#rules-that-compare-two-fields).
idempotency\_key\_reused
This `Idempotency-Key` was already used, within the last 24 hours, for a different request (a different method, path or body). Generate a new key for each new operation, and reuse a key only to retry exactly the same request.
unknown\_osaid
No OSA user has this OSAID. Check it with the adjuster: an OSAID exists once they have signed in to the OSA app, and they can read it there. With a test key, every OSAID that isn't one of your firm's test accounts gets this code.
adjuster\_not\_in\_firm
The adjuster hasn't joined your firm, or is no longer active in it. [Invite them](/api-reference/adjusters/invite-an-adjuster-to-your-firm) and wait for them to accept. Real adjusters are invisible to test keys, so a test key naming one also gets this code.
adjuster\_not\_accepting
The adjuster is in your firm but can't take claims right now: they don't have the permission to accept claims, or they have paused assignments. Choose another adjuster. The API has no way to check this in advance; handle it when it happens.
environment\_mismatch
Live keys can't send or offer claims to test accounts, can't invite test accounts, and can't offer test claims. Use your test key for test claims and test accounts. See [Testing](/testing).
rate\_limited
Wait for the number of seconds in the `Retry-After` header, then retry. See [Limits](/limits-and-idempotency).
internal\_error
Something failed on OSA's side. Retry with exponential backoff, reusing the same `Idempotency-Key` for `POST` requests; if it persists, contact OSA with the `request_id`. Other `5xx` responses (for example from the network in front of the API) may not have a problem body; treat them the same way.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.