Status codes

SOSfinder uses standard HTTP status codes. 2xx means success; 4xx means a problem with the request; 5xx means a problem on our side.

Quick reference

Code	Meaning	What to do
200	OK	Request succeeded — read the results.
400	Bad Request	Check required fields (query, state).
401	Unauthorized	Missing or invalid API key.
403	Forbidden	Key lacks access to this resource.
404	Not Found	No entity matched the query.
429	Too Many Requests	Slow down and retry with backoff.
500	Server Error	Retry shortly; contact support if it persists.
503	Service Unavailable	Temporary outage — retry with backoff.

Errors return a consistent JSON body with a machine-readable code and message.

{
  "success": false,
  "error": {
    "code": "invalid_state",
    "message": "\"ZZ\" is not a valid state code."
  }
}