Error Codes

Error Response Format

All API errors return a consistent JSON format:

{
  "error": "UnauthorizedError",
  "message": "Authentication required. Please provide a valid Bearer token.",
  "statusCode": 401
}

OAuth Errors

OAuth endpoints return errors in the standard OAuth format:

{
  "error": "invalid_client",
  "error_description": "Client not found or invalid credentials",
  "message": "Client not found or invalid credentials",
  "statusCode": 400
}

HTTP Status Codes

Success (2xx)

Code	Description
200	OK — Request successful
201	Created — Resource created
204	No Content — Request successful, no body

Client Errors (4xx)

Code	Description
400	Bad Request — Invalid request format or parameters
401	Unauthorized — Missing or invalid authentication
402	Payment Required — Insufficient credit balance
403	Forbidden — Valid auth but insufficient permissions
404	Not Found — Resource doesn't exist
406	Not Acceptable — Client doesn't accept required content types
409	Conflict — Resource conflict (e.g., duplicate)
422	Unprocessable Entity — Validation failed
429	Too Many Requests — Rate limit exceeded

Server Errors (5xx)

Code	Description
500	Internal Server Error
502	Bad Gateway — Upstream provider error
503	Service Unavailable
504	Gateway Timeout

Common Errors

Authentication Errors (401)

Error	Description
UnauthorizedError	Missing or invalid Bearer token
TokenExpiredError	Access token has expired — refresh it
InvalidTokenError	Token is malformed or signature invalid
SessionRevokedError	The auth session was revoked

Authorization Errors (403)

Error	Description
ForbiddenError	Token lacks required scopes
InsufficientScopeError	Specific scope missing for this endpoint

Credit Errors (402)

Error	Description
CreditsExhaustedError	Account has no remaining credits

Rate Limit Errors (429)

Error	Description
TooManyRequestsError	Rate limit exceeded

Response includes Retry-After header indicating when to retry.

OAuth Errors (400)

Error	Description
invalid_client	Client not found or invalid credentials
invalid_request	Missing required parameter
invalid_grant	Authorization code invalid, expired, or already used
unsupported_grant_type	Grant type not supported
invalid_scope	Requested scope not allowed
access_denied	User denied authorization

MCP Tool Errors

Tool errors are returned as JSON-RPC error responses:

Error	Description
McpToolUnauthorizedError	No valid authentication for tool execution
McpToolInsufficientCreditsError	Insufficient credits for tool execution
McpToolPromptInjectionBlockedError	Prompt injection detected and blocked
McpToolAgentExecutionError	Agent execution failed

Validation Errors (422)

{
  "error": "ValidationError",
  "message": "Validation failed",
  "statusCode": 422
}

Error Handling Best Practices

1. 401 — Try refreshing the token. If refresh fails, redirect to re-authorize.
2. 402 — Inform the user their credits are exhausted. Don't retry.
3. 429 — Wait and retry with exponential backoff. Check Retry-After header.
4. 5xx — Retry with exponential backoff (max 3 retries).

async function callApi(url, options) {
  const response = await fetch(url, options);

  if (response.status === 401) {
    const newToken = await refreshToken();
    options.headers.Authorization = `Bearer ${newToken}`;
    return fetch(url, options);
  }

  if (response.status === 429) {
    const retryAfter = response.headers.get("Retry-After") || 60;
    await sleep(retryAfter * 1000);
    return fetch(url, options);
  }

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

  return response;
}