Common Patterns

Error Handling

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

Error response format

All errors return JSON with this structure:


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

The errors object is only present for validation errors.

Code	Meaning	When it occurs
400	Bad Request	Invalid request body or parameters
401	Unauthorized	Missing, invalid, or expired API key
403	Forbidden	API key doesn't have permission for this action
404	Not Found	Resource doesn't exist or belongs to another organization
422	Validation Error	Request body failed validation
429	Too Many Requests	Rate limit exceeded
503	Service Unavailable	Temporary server issue

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`

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)

Last modified on April 20, 2026