Errors

Errors use HTTP status codes and a JSON body in the RFC 9457 problem details format, with Content-Type: application/problem+json.

json

{
  "type": "https://docs.sentinara.org/errors#unknown_parameter",
  "title": "Unknown query parameter",
  "status": 400,
  "code": "unknown_parameter",
  "detail": "\"regoin\" is not supported here. Allowed: region, level, q, sort, has_cases, format, limit, cursor.",
  "instance": "/v1/countries",
  "request_id": "8d3f2c1a9b7e4f60",
  "parameter": "regoin"
}

Branch on code, which is stable. title and detail are for humans and may change.
Quote request_id when you contact us; it is also in the X-Request-Id header of every response.
Errors are readable from browsers (Access-Control-Allow-Origin: *) and are never cached (Cache-Control: no-store).

#Error codes

Code	Status	Meaning	What to do	Retry
`invalid_parameter`	400	A query parameter has an invalid value (wrong format, out of range, repeated).	Check the parameter against the reference. The response names the parameter.	no
`unknown_parameter`	400	A query parameter is not supported by this endpoint.	Remove it or fix the spelling. Unknown parameters are rejected so typos do not silently return unfiltered data.	no
`api_key_in_query`	400	An API key was sent in the URL.	Send it in the Authorization or X-API-Key header. Treat the key as exposed and rotate it.	no
`invalid_body`	400	The JSON body is malformed or a field is invalid.	Fix the field named in the response.	no
`turnstile_failed`	400	The human verification token is missing, invalid or expired.	Complete the verification again on docs.sentinara.org/keys.	no
`invalid_key`	401	The key is malformed, unknown, or the Authorization header is not a Bearer token.	Check that you copied the whole key and use "Authorization: Bearer ".	no
`key_revoked`	401	The key was revoked (by you, by rotation, or for abuse).	Create a new key.	no
`management_token_required`	403	Rotating or revoking a publishable key needs its management token, sent from a server or terminal.	Send the token you received at creation in the X-Management-Token header, without an Origin header. If it is lost, email api@sentinara.org with the key prefix.	no
`secret_key_in_browser`	403	A secret key was used from a web page (the request had an Origin header).	Call the API from your server, or use a publishable key restricted to your site. Rotate the secret key if it was shipped to browsers.	no
`origin_not_allowed`	403	A publishable key was used from an origin it is not registered for.	Use the key only on its registered origins, or create a key for this origin.	no
`not_found`	404	The endpoint or the resource (country, province, sub-district) does not exist.	Check the path and identifier. List endpoints return valid identifiers.	no
`not_available`	404	The resource exists but this view is not available, e.g. no forecast for a country with too little data.	Use the profile endpoint to see the warning status and its reason.	no
`method_not_allowed`	405	The HTTP method is not supported here.	Use the method in the Allow header.	no
`not_acceptable`	406	CSV was requested from an endpoint that returns a single object.	Request JSON, or use a list endpoint.	no
`key_limit_reached`	409	Too many active keys for this email from your network (409), or too many keys created from your network in 24 hours (429).	Revoke an unused key, or wait.	no
`payload_too_large`	413	The request body is larger than 4 KB.	Send a smaller body.	no
`unsupported_media_type`	415	The body is not application/json.	Set Content-Type: application/json.	no
`rate_limited`	429	Too many requests in the current minute for your tier.	Wait for Retry-After seconds, then slow down. Use exponential backoff and caching.	yes
`quota_exceeded`	429	The daily quota of the key is used up.	Wait until 00:00 UTC (Retry-After). Cache responses; the data changes weekly.	yes
`internal_error`	500	Unexpected error on our side.	Retry with backoff. If it persists, report the request_id.	yes
`upstream_unavailable`	502	A dataset or the verification service could not be reached.	Retry with backoff after a few seconds.	yes
`not_configured`	503	A feature (key issuance) is not enabled on this deployment.	Use anonymous access, or try again later.	yes

#Retrying

Retry only codes marked yes, with exponential backoff and jitter, and honour Retry-After. Never retry 400, 401, 403 or 404 unchanged: the result will be the same.