Errors
How the Knips Public API reports errors.
Every error uses the same JSON shape and a standard HTTP status code, so you can handle them uniformly.
Error shape
{
"error": {
"type": "unauthorized",
"message": "Authentication required. Provide an API key via Basic auth."
}
}type— a stable, machine-readable string. Branch on this in code.message— a human-readable explanation. May change; don't match on it.
Status codes
| Status | type | Meaning |
|---|---|---|
400 | bad_request | A query parameter or body failed validation. |
401 | unauthorized | The API key is missing or invalid. |
404 | not_found | No such route or resource. |
500 | internal_error | An unexpected error on our side. |
502 | bad_gateway | An upstream service could not be reached. |
504 | gateway_timeout | An upstream service took too long to respond. |
Handling errors
- Branch on the HTTP status first, then on
error.typefor detail. 401→ check that your API key is present and valid.5xx→ transient. Retry with exponential backoff; these are usually not your fault.
A 502 or 504 means the request reached us but a service behind the API was
unavailable or slow. Retrying after a short delay normally succeeds.