# Errors

> Error response format and the HTTP status codes the API returns.

Source: https://tickos.dev/docs/errors

TickOS uses conventional HTTP response codes: 2xx for success, 4xx for client errors and 5xx for server errors. Error responses are JSON objects with an error field containing a human-readable message:

```json
{
  "error": "subject is required"
}
```

Authentication, permission and rate limit errors also include a message field with more detail. A few endpoints add extra context fields (for example, POST /v1/emails returns domain and help when the sender domain is not configured or verified). Always read error first and treat any other field as optional.

401 response:

```json
{
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked"
}
```

## HTTP status codes

| Code | When |
|---|---|
| 400 | Missing or malformed parameters, or an operation that is not valid for the current state (e.g. deleting an active automation). |
| 401 | Missing or invalid API key. |
| 403 | The API key does not have the required permission, the feature is not included in your plan, or the action is not allowed (e.g. the customer is blocked from creating tickets, the account is suspended). |
| 404 | The requested resource does not exist in your workspace. |
| 409 | Conflict with existing data: duplicates (tag name in the same inbox, contact group name, domain, inbox email address, pending invitation, existing member) or state conflicts (deleting a non-draft campaign, deleting a connection with active inboxes). |
| 413 | Payload too large: the email built by POST /v1/tickets/compose exceeds the maximum sendable size. |
| 422 | A recipient is suppressed (too many bounces or marked undeliverable), so the email is not sent. |
| 429 | Rate limit exceeded, or a plan quota was reached. See below. |
| 500 | Internal server error. Safe to retry idempotent requests. |

## 429: rate limit vs. plan quota

HTTP 429 is used for two different situations. Check the error field to tell them apart.

| error | Meaning | What to do |
|---|---|---|
| Rate limit exceeded | Too many requests per minute for this key (see Rate limits). | Wait Retry-After seconds and retry. |
| Limit exceeded | A plan quota was reached (e.g. monthly, daily or hourly emails, recipients per email, storage). | Do not retry immediately: wait for the quota period to reset (hourly, daily or monthly) or upgrade the plan. |

Plan quota reached:

```json
{
  "error": "Limit exceeded",
  "message": "Email limit reached (3000/3000). Upgrade or wait for period reset.",
  "current": 3000,
  "limit": 3000,
  "percentage": 100,
  "recommended_plan": "starter"
}
```

Team member limits (POST /v1/members and POST /v1/invitations) also return 429, but with only the error field.