# Error Codes

The error format and every error code, with what each one means and what to do.

Source: https://docs.itsconvo.com/errors

API Base URL: https://www.itsconvo.com/api/v1

All errors look the same.

```json
{ "error": { "code": "not_found", "message": "Conversation not found" } }
```

- Handle errors by `code`. The codes below don't change.
- `message` is for people and can change. For `validation_error` it names the field.
- A request without an `Authorization` header can get a `429` with a different body. See [Rate Limits](/rate-limits#other-429-responses).

## Codes

| Code | Status | Meaning | What to do |
|------|:------:|---------|------------|
| `validation_error` | 400 | A field or parameter is missing or wrong, or the body isn't valid JSON. Feedback also returns it for a call with fewer than 10 transcript segments. | Fix the request |
| `unauthorized` | 401 | The `Authorization` header is missing, or the key is wrong or revoked | See [Authentication](/authentication#when-authentication-fails) |
| `forbidden` | 403 | The plan doesn't allow the request. This covers a Free plan or ended subscription, webhooks below Professional, the webhook limit, a contact briefing without Convo Memory, revoked calendar access, and a key from an MCP sign-in. | Read the message |
| `not_found` | 404 | No such call, webhook or contact in your account, or the call was deleted. Also returned when key points or feedback don't exist yet, when renaming a call without key points, and when no calendar is connected. | Check the ID. Generate key points or feedback with `POST`. |
| `rate_limited` | 429 | Over the hourly request limit, or the AI model is busy | Wait `Retry-After` seconds, or a few seconds when there is no header |
| `ai_limit_exceeded` | 429 | Your AI credits are used up for the month or the day, or the spending cap is reached | Don't retry. See [Tier Access](/tiers#ai-credits). |
| `internal_error` | 500 | Something failed on Convo's side | Retry once after a pause |

## Retrying

- Retry `rate_limited` and `internal_error`. Every other code means the request or the account has to change first.
- On `POST /feedback`, `/query` and `/email`, a `500` can come after the AI credit was used, so a retry uses another one.
- If an error persists, write to [ivan@itsconvo.com](mailto:ivan@itsconvo.com) with the endpoint, the time and the message.