Errors

The Spirii API uses standard HTTP status codes to signal the outcome of a request. A 2xx status means the request succeeded. A 4xx means something about the request needs fixing before it will work. A 5xx means the request was valid, but Spirii couldn’t complete it.

​

Status codes

These are the codes you’ll meet across the API. Each endpoint’s reference page lists the specific codes it can return — a 404, for instance, appears only where the request references a resource that might not exist. 401 and 403 both signal an access problem: 401 when a request isn’t authenticated, 403 when it’s authenticated but not permitted. Usage isn’t fully consistent across the API — some endpoints return 403 for an authentication failure — so treat either as an access issue, check your key and its permissions, and read the endpoint’s reference for the codes it returns. See Authentication for how to send the key correctly.

​

Error responses

An error response carries the status code and a human-readable message describing what went wrong. Read the status code to decide what your integration does next, and surface the message to whoever is operating the integration. Treat the message as descriptive text for a person, not a stable field to branch on in code — the status code is the contract.

​

Handling errors

How you respond depends on the class of error:

• 4xx — fix the request. A validation error, a missing resource, or an auth problem won’t resolve on its own. Don’t retry the same request unchanged; correct it first. A 409 is the exception: the request may be valid but the resource is already in the target state, so read the current state before deciding whether to retry.
• 5xx — retry with backoff. A 500 or 502 is usually transient. Retry with exponential backoff and a ceiling on attempts rather than looping immediately.
• Rate limiting. Requests beyond the limit are rejected. Back off and retry, and see Rate limits for the current limit and how to stay under it.

​

Related