# Errors

An error body looks like this:

```json
{"success": false, "message": "API key has to be provided",
 "error": {"code": "api_key_missing", "message": "API key has to be provided",
           "docs_url": "https://twitterscore.io/developers/errors/"}}
```

`success: false` is present on every error. The `error` object is present on authentication, account-lookup, rate-limit and unexpected errors; parameter checks made by individual endpoints (for example an unknown `by`, `days`, date or `category_id` value) still answer with `success: false` and `message` only, and with HTTP 200. One endpoint (`get_categorized_followers_count`) can answer an internal failure with a legacy body where `error` is a plain string and `message` is absent. So branch on `success` first, treat `message` and `error` as optional, and check that `error` is an object before reading `error.code`.

## HTTP statuses

Clients built on the first version of the API branch on the body, not on the status code. For that reason errors are **currently returned with HTTP 200** and `success: false`; the two rate limits (`rate_limited`, `quota_exceeded`) are the exception and already answer with HTTP 429. The real HTTP statuses for the other codes are enabled after a 30-day notice in the [Changelog](/developers/changelog/). Code that checks `success` first works before and after the switch.

## Codes

| `error.code` | Meaning | HTTP status today | HTTP status after the switch |
|---|---|---|---|
| `api_key_missing` | No API key in the request. | 200 | 401 |
| `api_key_invalid` | The key is unknown. | 200 | 401 |
| `api_access_deactivated` | API access of the account is off (expired or cancelled plan): renew on the dashboard. | 200 | 403 |
| `api_key_revoked` | This key was revoked; the account is still active, create a new key. | 200 | 403 |
| `invalid_params` | A required parameter is missing or malformed. | 200 | 400 |
| `account_not_found` | No tracked account matches the username / twitter_id. | 200 | 404 |
| `method_not_allowed` | Only GET is supported. Sent for HEAD/OPTIONS; POST and other unsafe methods are stopped earlier with an HTML 403. | 200 | 405 |
| `rate_limited` | Per-minute rate exceeded; retry after `Retry-After` seconds. | 429 | 429 |
| `quota_exceeded` | Monthly quota exhausted; upgrade or wait for the window to reset. | 429 | 429 |
| `server_error` | Unexpected server error; retry later. | 200 | 500 |

`rate_limited` responses carry `Retry-After: 60` (the length of the per-minute window; waiting that long is always enough); `quota_exceeded` has no `Retry-After` (the 30-day window resets on its own, see [Rate limits](/developers/rate-limits/)).