Palmframe API

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"
    }
  }
}
FieldTypeDescription
error.codestringA stable, machine-readable identifier for the error.
error.messagestringA human-readable description of what went wrong.
error.detailsobjectOptional. Extra context, e.g. field-level validation messages.

Error codes

CodeHTTP statusMeaning
invalid_request400The request was malformed — bad JSON, or an invalid query parameter.
unauthorized401The API key is missing, malformed, or revoked.
forbidden403The key is valid but not allowed to perform this action.
not_found404No resource exists at the requested path or id.
method_not_allowed405The HTTP method is not supported for this endpoint.
conflict409The request conflicts with the current state of a resource.
validation_failed422The body was well-formed but failed validation. See details.
rate_limited429Too many requests. Slow down and retry after a short delay.
internal_error500Something 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}`);
  }
}

On this page