# Errors

> The single error format of the Socialit API, its error types and HTTP status codes, and how to handle network errors.

Every error, from validation to a network refusing a post, uses one shape:

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_failed",
    "message": "The post cannot be published to X.",
    "param": "content",
    "errors": { "content": ["Too long for X (280)"] },
    "platform": "x",
    "platform_code": "186",
    "doc_url": "https://socialit.com/docs/networks/x/"
  },
  "request_id": "req_4hQx…"
}
```

| Field | Meaning |
|---|---|
| `type` | The category (table below). Branch on this first. |
| `code` | A stable, specific code such as `validation_failed`, `invalid_api_key` or `plan_required`. |
| `message` | A human-readable explanation. Don't parse it. |
| `param` | The request field the error is about, when there is one. |
| `errors` | Field-by-field messages for validation errors. |
| `platform`, `platform_code` | The network and its own error code, when the network refused. |
| `request_id` | Include it when you contact support. |

## Types

| `type` | Status | When |
|---|---|---|
| `invalid_request_error` | 400, 422 | Malformed request or validation failed |
| `authentication_error` | 401 | Missing, invalid or revoked credentials |
| `permission_error` | 403 | The credential can't do this, or can't access this profile |
| `not_found_error` | 404 | The object doesn't exist or isn't visible to you |
| `conflict_error` | 409 | The request conflicts with the current state, or reused an idempotency key |
| `plan_limit_error` | 402, 403 | Your plan doesn't include this, or a limit was reached; includes `usage` and `required_plan` |
| `rate_limit_error` | 429 | Too many requests; see [Rate limits](/docs/api-reference/rate-limits/) |
| `platform_error` | 502 | The network returned an error |
| `api_error` | 500 | Something went wrong on our side |

## Handling them

- `4xx` errors won't succeed if repeated unchanged. Fix the request first.
- Retry `429`, `502` and `5xx` with exponential backoff, and use an [idempotency key](/docs/api-reference/idempotency/) so retries are safe.
- `409 conflict_error` with code `account_needs_reconnect` means the account's token was revoked: reconnect it (the error and the `account.needs_reconnect` webhook carry the account). `403 missing_scopes` lists `missing_scopes` and a `reconnect_url` that upgrades them.
- `403 plan_limit_error` with `plan_required` names the `required_plan`; `402 insufficient_credits` means prepaid X credits ran out. See [Billing and usage](/docs/billing-usage/#plan-errors).
- Network-specific operations answer `409 capability_not_supported` (or `422 not_supported`) when a network can't do something, with `platform` and `capability`.

---

Source: https://socialit.com/docs/api-reference/errors/
