# Errors

> Every error code, what it means and what to do.

Errors use normal HTTP status codes and always have the same JSON shape: an `error` code you can switch on, and usually a short `message`.

```json
{ "error": "insufficient_credits", "message": "this score costs 10 credits" }
```

Invalid domains also carry a one-word `reason` (see [Domain checks](/domain-checks)):

```json
{ "error": "invalid_domain", "reason": "file_name" }
```

**Switch on `error` (and `reason`), not on `message`.** Messages are for people and may change.

## All error codes

| HTTP | `error` | Endpoints | What to do |
|---|---|---|---|
| 400 | `invalid_input` | All | Fix the field named in `message` (or send valid JSON) |
| 400 | `invalid_domain` | Scoring, company | Send the company's own website. `reason` says what was wrong |
| 400 | `invalid_email` | `/score/email`, email → domain | Send a valid email address |
| 400 | `invalid_url` | `/score/social` | Send a LinkedIn company or person URL (`reason: not_linkedin`) |
| 400 | `too_many_inputs` | `/score/…/bulk` | Send at most 1,000 inputs per call |
| 400 | `too_many_domains` | Bulk | Send at most 1,000 domains per call |
| 400 | `too_many_emails` | Email bulk | Send at most 1,000 emails per call |
| 401 | `unauthorized` | All | Send a valid key: `Authorization: Bearer plx_live_…` |
| 402 | `insufficient_credits` | Scoring, company, email → domain | Top up credits in the app |
| 403 | `template_not_allowed` | Scoring | Use one of your own templates |
| 404 | `job_not_found` | Score | Check `job_id`. Jobs are visible only to the account that started them |
| 404 | `batch_not_found` | Bulk | Check `batch_id` |
| 404 | `not_found` | `/score/…` | Unknown path: use `/score/domain`, `/score/email` or `/score/social` |
| 405 | `method_not_allowed` | All | Use the method shown in the reference |
| 409 | `template_not_live` | Scoring | Use the template with `is_live: true` |
| 409 | `batch_in_progress` | Bulk scoring | Wait for your running batch to finish |
| 422 | `template_empty` | Scoring | Switch on at least one signal in your live template |
| 500 | `internal_error` | All | Something failed on our side. Try again |
| 502 | `provider_unavailable` | Company, email → domain | A data source didn't answer. Try again; nothing was charged |

## Retrying

- **Safe to retry:** `500`, `502`, and network errors. Wait a few seconds, then back off.
- **Don't retry unchanged:** `400`, `401`, `403`, `404`, `422`. The same request will fail the same way.
- **Retry later:** `402` after topping up; `409 batch_in_progress` after the running batch completes.
- **Scoring is safe to repeat:** sending the same domain again returns the running or recent job instead of charging twice.
