API
Error Codes
Error handling reference for the TBit API
# Error Codes > Error handling reference for the TBit API - Page: https://tbit.app/docs/api/errors - Base URL: `https://rest-api.tbit.app/v1` - Authentication: `X-API-Key` header with your key on every request (the examples read it from the `TBIT_API_KEY` environment variable) Looking for why a WhatsApp message was not delivered? See [WhatsApp delivery errors](https://tbit.app/docs/whatsapp-delivery-errors). ## Error Response Format All errors follow a consistent JSON structure: ```json { "error": { "code": "NOT_FOUND", "message": "Activity not found" } } ``` ## Error Codes | Status | Code | Description | | --- | --- | --- | | `400` | `VALIDATION_ERROR` | Invalid request body or query parameters | | `401` | `UNAUTHORIZED` | Missing or invalid API key | | `404` | `NOT_FOUND` | Resource not found or does not belong to your agent | | `405` | `METHOD_NOT_ALLOWED` | HTTP method not supported for this endpoint | | `409` | `CONFLICT` | Resource already exists (e.g., contact with this channel) | | `422` | `SEND_FAILED` | Template send failed (e.g., no messaging window) | | `429` | `RATE_LIMITED` | Rate limit exceeded (100 requests/minute) | | `500` | `INTERNAL_ERROR` | Unexpected server error | ## Rate Limit Headers Every response includes rate limit information in headers: | Header | Description | | --- | --- | | `X-RateLimit-Remaining` | Requests remaining in current window | | `X-RateLimit-Reset` | Timestamp (ms) when the window resets | ## Error Handling Best practices for handling API errors: - Always check the HTTP status code before parsing the response body - Implement exponential backoff for 429 (rate limit) errors - Log error codes and messages for debugging - Do not retry 400 or 401 errors: fix the request firstLooking for why a WhatsApp message was not delivered? See WhatsApp delivery errors.
All errors follow a consistent JSON structure:
{
"error": {
"code": "NOT_FOUND",
"message": "Activity not found"
}
}| Status | Code | Description |
|---|---|---|
400 | VALIDATION_ERROR | Invalid request body or query parameters |
401 | UNAUTHORIZED | Missing or invalid API key |
404 | NOT_FOUND | Resource not found or does not belong to your agent |
405 | METHOD_NOT_ALLOWED | HTTP method not supported for this endpoint |
409 | CONFLICT | Resource already exists (e.g., contact with this channel) |
422 | SEND_FAILED | Template send failed (e.g., no messaging window) |
429 | RATE_LIMITED | Rate limit exceeded (100 requests/minute) |
500 | INTERNAL_ERROR | Unexpected server error |
Every response includes rate limit information in headers:
| Header | Description |
|---|---|
X-RateLimit-Remaining | Requests remaining in current window |
X-RateLimit-Reset | Timestamp (ms) when the window resets |
Best practices for handling API errors:
- Always check the HTTP status code before parsing the response body
- Implement exponential backoff for 429 (rate limit) errors
- Log error codes and messages for debugging
- Do not retry 400 or 401 errors: fix the request first