Skip to content
timbl

Error Codes

Every failed API request returns a JSON error envelope. The code field is a stable string from @timbl/core’s ErrorCodes enum.

{
  "code": "VALIDATION_ERROR",
  "message": "Validation failed",
  "details": {},
  "requestId": "..."
}

The message is human-readable and may change between releases. The code is stable and covered by semver. Match on code in your client logic, not on message.

All error codes

CodeHTTP statusWhen it is thrown
VALIDATION_ERROR400A field failed validation, or the request body did not match the collection schema
REGISTRY_ERROR500The registry could not build or resolve a collection, global, plugin, or field definition
NOT_FOUND404A requested resource (collection entry, global, asset) does not exist
CONFLICT409A write conflicts with existing data, such as a duplicate slug or unique constraint violation
UNAUTHORIZED401The request requires authentication and no valid principal was resolved
FORBIDDEN403The principal was resolved but lacks the capability for the requested operation
ADAPTER_ERROR500A configured adapter (database, auth, storage, HTTP) failed an operation
PLUGIN_ERROR500A plugin threw during setup, hook execution, or route handling
RUNTIME_ERROR500A runtime operation failed outside a specific adapter or plugin boundary
NOT_IMPLEMENTED501The requested operation is valid but the current adapter does not implement it
PAYLOAD_TOO_LARGE413An upload exceeded the configured size limit
EXPORT_TOO_LARGE500The content export exceeded the maximum payload size
INTERNAL_ERROR500An uncaught error with no specific code

Using error codes in a client

The @timbl/client SDK throws TimblHttpError on non-2xx responses. Inspect the code property to decide how to react.

import { TimblHttpError } from "@timbl/client";


try {
  await client.collection("posts").findBySlug("missing");
} catch (error) {
  if (error instanceof TimblHttpError && error.code === "NOT_FOUND") {
    // render a 404 page
  } else {
    throw error;
  }
}

The requestId in the error envelope is also available on the thrown error. Include it in bug reports so maintainers can trace the request in logs.

Error envelope shape

The envelope is the same for every endpoint. details is an optional object that carries field-level validation errors or other structured context.

type ErrorEnvelope = {
  code: ErrorCode;
  message: string;
  details?: Record<string, unknown>;
  requestId: string;
};

See also