Developers
The error envelope
The consistent error shape returned by the public API.
Successful responses return the resource directly (an object, or a paginated list). Failed responses always use one envelope:
{
"ok": false,
"error": {
"code": "NOT_FOUND",
"message": "The requested resource was not found.",
"ref": "err_01J..."
}
}code: a stable, machine-readable error code.message: a human-readable, safe message.ref: a unique reference for the request. Include it if you contact support.
Codes you may see
| HTTP | code | When |
|---|---|---|
| 400 | VALIDATION_FAILED | a query parameter is invalid (for example limit over 50) |
| 401 | UNAUTHORIZED | the x-api-key you sent is invalid or revoked |
| 404 | NOT_FOUND | no resource matches the slug or username |
| 429 | RATE_LIMITED | you exceeded your rate limit |
| 503 | SERVICE_UNAVAILABLE | a backing service is temporarily unavailable |
Handling errors
const res = await fetch(url, { headers: { 'x-api-key': key } })
const body = await res.json()
if (!res.ok || body.ok === false) {
// body.error.code, body.error.message, body.error.ref
throw new Error(`${body.error.code}: ${body.error.message}`)
}A missing key is not an error: keyless requests simply use the lower rate tier.
Last updated: 18 June 2026