Error Handling

Error response format and common error codes.

Error Format

Every error includes an error message and a code:

Error response

{
  "error": "Short human-readable message",
  "code": "ERROR_CODE"
}

Validation errors include additional details:

Validation error

{
  "error": "Validation failed",
  "code": "VALIDATION_ERROR",
  "errors": [
    { "path": "/body/name", "message": "must be string" }
  ]
}

Common Error Codes

Status	Code	Description
`400`	`VALIDATION_ERROR`	Request body or parameters are invalid.
`401`	`UNAUTHORIZED`	Missing or invalid API key.
`402`	`INSUFFICIENT_BALANCE`	Not enough credits for the operation.
`402`	`PAYMENT_FAILED`	Company activation payment failed.
`403`	`FORBIDDEN`	Company is not active.
`404`	`NOT_FOUND`	Resource does not exist.
`409`	`ALREADY_PROCESSED`	Activation already processed.
`409`	`CONVERSATION_CLOSED`	Conversation is no longer active.
`500`	`INTERNAL_ERROR`	Unexpected server error.

Handling 402 Errors

If you receive INSUFFICIENT_BALANCE, the company's plan does not cover the action and there are not enough prepaid credits. Purchase credits via POST /api/companies/credits/purchase and retry.

Best Practices

Always check the code field, not the HTTP status, for programmatic error handling.
Log the full error response for debugging.
Present the error message to users when appropriate.
Implement retry logic with exponential backoff for 500 errors.

← Previous Authentication Next → JavaScript SDK