Error Handling

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

HTTP	ORPC Code	data.code	Notes
400	`BAD_REQUEST`	`VALIDATION_ERROR`	Input validation failed
401	`UNAUTHORIZED`	`AUTH_REQUIRED`	Missing or invalid JWT
403	`FORBIDDEN`	`ACCESS_DENIED`	Permission denied
403	`ORG_CONTEXT_REQUIRED`	`ORG_CONTEXT_REQUIRED`	Org context required
403	`PAYMENT_REQUIRED`	`PAYMENT_REQUIRED`	Subscription required
404	`NOT_FOUND`	`RESOURCE_NOT_FOUND`	Resource missing
409	`CONFLICT`	`DUPLICATE_RESOURCE`	Resource already exists
500	`INTERNAL_SERVER_ERROR`	`INTERNAL_ERROR`	Server error

Handling Errors

JavaScript
Python

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();
}

import requests

response = requests.post(
    "https://app.usechar.ai/api/organization-skills/list",
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
    },
    json={"limit": 20, "offset": 0},
)

if response.status_code >= 400:
    error = response.json()
    raise Exception(f"{error['code']}: {error['message']}")

data = response.json()

API Reference

SDK Reference

Agent Reference

MCP Reference

Security Reference

Auth

OAuth

Subscriptions

End Users

Users

Organizations

Organization Skills

User Scripts

Directories

Plan Tiers

Threads

Usage Analytics

Identity Providers

Governance

GitHub Apps

Publishable Keys

OAuth Discovery

Error Handling

Error Response Format

Common Error Codes

Handling Errors

​Error Response Format

​Common Error Codes

​Handling Errors

Error Response Format

Common Error Codes

Handling Errors