Chatmaid Developers

Error Envelope

Most API errors follow this envelope.

Standard Error Shape

{
  "success": false,
  "error": "Unauthorized",
  "message": ["Invalid API key"],
  "statusCode": 401,
  "timestamp": "2026-02-06T14:22:30.000Z",
  "path": "/v1/messages/send"
}

Validation errors return the same shape, with multiple entries in message.

Validation Error Example (400)

{
  "success": false,
  "error": "Bad Request",
  "message": [
    "Phone number must be in E.164 format (e.g., +1987654321)",
    "to must be a string"
  ],
  "statusCode": 400,
  "timestamp": "2026-02-06T14:22:30.000Z",
  "path": "/v1/messages/send"
}

Common Errors

Common Error Matrix

Code	Cause	Typical Fix
`400`	Invalid payload or query values	Fix request format, required fields, or value constraints.
`401`	Missing, invalid, or expired API key	Send a valid Bearer API key from dashboard.
`403`	Missing scope or inactive subscription	Use a key with correct scope and ensure account is active.
`404`	Unknown message/phone resource	Verify identifiers belong to your account.
`429`	Per-key rate limit exceeded	Back off and retry after retryAfter seconds.
`500`	Unexpected internal error	Retry safely and contact support with messageId/request context.

Rate Limit Error Example (429)

{
  "success": false,
  "error": "Rate limit exceeded",
  "retryAfter": 60
}

Debug Workflow

Verify Authorization: Bearer sk_live_* or sk_test_* header format.
Check key scopes include required permissions (for phone endpoints, include phone_numbers:read).
Confirm sender phone is connected in dashboard.
If using phone number in path, URL-encode it (for example %2B15551234567).
Use idempotency keys and inspect message status endpoint.

Operational Tip

Log messageId values from send responses and use them as the canonical correlation key across polling, webhook processing, and support tickets.