Errors
How the Palmframe API reports errors, and what each error code means.
Palmframe uses conventional HTTP status codes to indicate the outcome of a
request. 2xx codes mean success, 4xx codes indicate a problem with the
request (a missing field, an unknown id, an invalid key), and 5xx codes
indicate a problem on Palmframe's side.
Error envelope
Every error response has the same shape: a top-level error object with a
machine-readable code, a human-readable message, and an optional details
field carrying additional context (such as per-field validation errors).
{
"error": {
"code": "validation_failed",
"message": "The request body is invalid.",
"details": {
"title": "title is required"
}
}
}| Field | Type | Description |
|---|---|---|
error.code | string | A stable, machine-readable identifier for the error. |
error.message | string | A human-readable description of what went wrong. |
error.details | object | Optional. Extra context, e.g. field-level validation messages. |
Error codes
| Code | HTTP status | Meaning |
|---|---|---|
invalid_request | 400 | The request was malformed — bad JSON, or an invalid query parameter. |
unauthorized | 401 | The API key is missing, malformed, or revoked. |
forbidden | 403 | The key is valid but not allowed to perform this action. |
not_found | 404 | No resource exists at the requested path or id. |
method_not_allowed | 405 | The HTTP method is not supported for this endpoint. |
conflict | 409 | The request conflicts with the current state of a resource. |
validation_failed | 422 | The body was well-formed but failed validation. See details. |
rate_limited | 429 | Too many requests. Slow down and retry after a short delay. |
internal_error | 500 | Something went wrong on Palmframe's side. Retry later. |
Handling errors
Check the HTTP status first, then branch on error.code for specific handling:
const res = await fetch("https://palmframe.com/api/v1/posts/post_missing", {
headers: { Authorization: `Bearer ${key}` },
});
if (!res.ok) {
const { error } = await res.json();
switch (error.code) {
case "not_found":
// handle a missing resource
break;
case "rate_limited":
// back off and retry
break;
default:
throw new Error(`${error.code}: ${error.message}`);
}
}