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. Zero matches also return 200, with success: false and an empty results list (not a 404).
401	Unauthorized	No API key was sent — add the x-api-key header.
402	Payment Required	Key validation failed: an invalid/revoked key, no credits remaining, or the burst rate guard. Read the error text — "Rate limit exceeded" means slow down and retry, anything else means check your key or top up.
422	Unprocessable Entity	Missing or malformed parameters — check state and business_name.
500	Server Error	Usually the state registry timing out upstream — retry shortly; email support@sosfinder.com if it persists.
503	Service Unavailable	Temporary outage — retry with backoff.

Key and credit problems (401 / 402) return a flat error string:

{ "error": "No credits remaining" }

Parameter validation (422) returns a detail array naming each bad field:

{
  "detail": [
    { "type": "missing", "loc": ["query", "business_name"],
      "msg": "Field required", "input": null }
  ]
}

An unsupported state returns 200 with an ErrorMessage and the list of covered states — check for it before reading results:

{
  "ErrorMessage": "Unsupported state: 'ZZ'",
  "supportedStates": ["alabama", "arkansas", "california", "…"]
}