Skip to main content
The Char API returns structured error responses with conventional HTTP status codes.

​
Error Response Format

{
  "code": "BAD_REQUEST",
  "status": 400,
  "message": "Invalid request data",
  "data": {
    "code": "VALIDATION_ERROR",
    "field": "name",
    "details": "Name is required"
  }
}
  • code is the ORPC error code (HTTP-aligned)
  • data.code is a machine-readable error identifier
  • data may include additional fields depending on the error type

​
Common Error Codes

HTTPORPC Codedata.codeNotes
400BAD_REQUESTVALIDATION_ERRORInput validation failed
401UNAUTHORIZEDAUTH_REQUIREDMissing or invalid JWT
403FORBIDDENACCESS_DENIEDPermission denied
403ORG_CONTEXT_REQUIREDORG_CONTEXT_REQUIREDOrg context required
403PAYMENT_REQUIREDPAYMENT_REQUIREDSubscription required
404NOT_FOUNDRESOURCE_NOT_FOUNDResource missing
409CONFLICTDUPLICATE_RESOURCEResource already exists
500INTERNAL_SERVER_ERRORINTERNAL_ERRORServer error

​
Handling Errors

async function listSkills(token) {
  const response = await fetch("https://app.usechar.ai/api/organization-skills/list", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${token}`,
    },
    body: JSON.stringify({ limit: 20, offset: 0 }),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`${error.code}: ${error.message}`);
  }

  return response.json();
}