Copy page

Common Patterns

Error Handling

The Qwetty API uses standard HTTP status codes and consistent error response formats.

Error response format

The API returns errors in two shapes depending on where they originate:

Authentication, permission, and rate-limit errors (thrown centrally) use:

Code
{
  "success": false,
  "message": "Human-readable error description",
  "errors": [
    { "field_name": "Field-specific error message" }
  ]
}

The errors array is only present for validation errors.

Endpoint-level errors (such as "not found" or a missing required field) are returned by the controller as:

Code
{
  "error": "Human-readable error description"
}

So when handling errors, check for both a message and an error field.

HTTP status codes

Code	Meaning	When it occurs
400	Bad Request	Invalid request body or missing required field
401	Unauthorized	Missing, invalid, or expired API key
403	Forbidden	API key lacks permission, IP not whitelisted, or monthly quota exceeded
404	Not Found	Resource doesn't exist or belongs to another organization
429	Too Many Requests	Rate limit exceeded

Common errors and solutions

Error	Cause	Solution
"Missing or invalid Authorization header"	No Bearer token	Add Authorization: Bearer YOUR_KEY header
"Invalid or expired API key"	Key doesn't exist, is revoked, or expired	Check your key in Settings → API Keys
"Rate limit exceeded"	Too many requests	Implement backoff; check rate limit headers
"Chat not found"	Chat ID doesn't exist or is not in your organization	Verify the chat ID with GET /chats

Rate limit headers

When rate-limited, the response includes:

Header	Description
X-RateLimit-Limit	Maximum requests per window
X-RateLimit-Remaining	Requests remaining
X-RateLimit-Reset	When the window resets (Unix timestamp)

Next steps

• Pagination & Filtering — Navigate large result sets
• Rate Limits — Detailed rate limit information