# Handling errors

Source: https://parasend.com/docs/handling-errors

Parasend answers with the usual HTTP status codes: `2xx` worked, `4xx` means the request needs to change, `5xx` means something went wrong on our side. Every error has the same body:

```json
{
  "error": {
    "type": "invalid_request",
    "code": "recipient_phone_invalid",
    "message": "recipient.phone must be in E.164 format (e.g. +3546661234).",
    "param": "recipient.phone",
    "doc_url": "https://parasend.com/docs/errors/recipient_phone_invalid",
    "request_id": "req_01M6P3QD4H8WZ2KX7N1R9T5V3B"
  }
}
```

| Field | What it is |
|---|---|
| `type` | The group the error belongs to (below). |
| `code` | A stable, specific code. Branch on this, never on `message`. Every code has its own page under [error codes](/docs/errors). |
| `message` | A sentence for a person to read. It can change. |
| `param` | When one parameter caused it, its name, as a dotted path such as `recipient.phone`. |
| `doc_url` | The code's page in these docs: what it means and what to do. |
| `request_id` | The request's ID, also in the `Request-Id` header. Give it to us when you ask for help. |

A few errors carry more fields, named on their own page.

## Error types

| Type | Status | What to do |
|---|---|---|
| `invalid_request` | 400, sometimes 404 | Fix the request. `code` and `param` say what is wrong. |
| `authentication_error` | 401 | Check the API key. See [authentication](/docs/authentication). |
| `permission_error` | 403 | The key lacks a permission, or the action is not allowed for this account. |
| `not_found` | 404 | No such object in this mode, or no such route. |
| `conflict` | 409 | The object's state does not allow this now, for example a reminder before the first notice has gone out (`remind_state_invalid`). |
| `payload_too_large` | 413 | The body or file is too large. |
| `rate_limited` | 429 | Wait, then try again. See [rate limits](/docs/rate-limits). |
| `api_error` | 500, 503 | Try again with the same `Idempotency-Key`. If it keeps happening, contact us with the `request_id`. |

## Retrying safely

- Retry `429`, `500`, `503` and network failures, with exponential backoff. When the answer has a `Retry-After` header, wait at least that many seconds.
- Send the **same** `Idempotency-Key` when you retry a `POST`. If the first attempt did go through, you get its answer back instead of a second delivery. See [idempotency](/docs/idempotency).
- Do not retry other `4xx` errors unchanged: they will fail the same way.

## Request IDs

Every answer carries a `Request-Id` header, such as `req_01M6P3QD4H8WZ2KX7N1R9T5V3B`. Log it with your own record of the call. You can also send your own `Request-Id` starting with `req_`, and Parasend uses it.