Skip to main content

​
Rate limits

Limits apply per key. For both kinds of key, and for requests and writes alike, at most 20 are accepted in the same instant. After a burst like that, capacity comes back steadily at the per-minute rate: for requests, five a second with a live key and one a second with a test key. So a test key that sends 25 requests at once gets 429 on the last five, although it is well under 60 a minute. Over the limit, you get 429 rate_limited with a Retry-After header giving the seconds to wait. Wait that long, then retry. No other rate-limit headers are sent.

​
Flood protection at the edge

Separately from the per-key limits, OSA’s network edge blocks any single IP address that sends more than 600 requests a minute. Normal integrations never reach it, because the per-key limits are lower. If you do, the response is a 429 with a plain HTML page, not the JSON error format, and it has no Retry-After or X-Request-Id header. Treat any 429 without a JSON body as “wait a minute, then retry”. Limits are enforced approximately, so plan to stay comfortably under them rather than at them. If you expect a surge, for example after a declared catastrophe, contact OSA: limits can be raised for your firm.

​
Idempotency

Networks fail. A request can succeed on OSA’s side while your system never sees the response. Idempotency-Key makes retrying safe. It is required on the two calls that create work for an adjuster:
  • POST /v1/claims
  • POST /v1/claims/{id}/assignment
The invitation calls take no Idempotency-Key and are safe to repeat without one. After a timeout, send the same call again: inviting an adjuster whose invitation is already pending answers 409 invitation_pending, and withdrawing an invitation that is already withdrawn answers 404 not_found. Either answer means your first request went through.
How it works:
  • Generate a new random value, such as a UUID, for each operation, and store it with the operation so a retry reuses it.
  • OSA matches the key with a fingerprint of the whole request: method, path and body. The body is compared as JSON, so the order of an object’s fields and the spacing don’t matter; any difference in a value does.
  • A retry of the same request with the same key within 24 hours returns the same status code, with the claim’s current state (so a claim the adjuster accepted in the meantime shows as accepted). Nothing new is created.
  • The same key with a different request is refused with 422 idempotency_key_reused. Never reuse a key for a different request.
  • If two identical requests arrive at once, one creates the claim and the other gets the same result.

​
After 24 hours

Your external_id is the second safety net. It is unique within your firm forever, so re-sending a claim days later returns 409 duplicate_claim with the existing claim’s id instead of creating a copy. A claim_number that matches one of your firm’s open claims sent through the API is also a duplicate. A claim is open from the moment you send it until it is closed in OSA, whatever its assignment status. So a rejected claim’s number is still taken: offer that claim to another adjuster instead of sending it again. The claim_number check is best-effort: two requests with the same claim_number and different external_ids that arrive at the same instant can both succeed. The external_id check has no such gap. Both checks are made separately for test and live keys, so test claims never collide with live ones.

​
Request size and format

Request bodies are limited to 1 MB; larger bodies get 413 payload_too_large. A body that isn’t valid JSON gets 400 malformed_request. Unknown query parameters are rejected with 422 validation_failed.

​
Retrying