# Error codes

The API uses standard HTTP status codes to indicate the result of a request.
Successful submissions return `2xx`; client and server errors return `4xx` and
`5xx` respectively.

| Status | Meaning | Description |
|  --- | --- | --- |
| `400` | Bad Request | The request was malformed or failed validation. |
| `401` | Unauthorized | Missing or invalid Bearer token. |
| `403` | Forbidden | The token is valid but not permitted for this action. |
| `404` | Not Found | The requested resource does not exist. |
| `413` | Payload Too Large | The request body exceeds the allowed size. |
| `429` | Too Many Requests | You have exceeded your account rate limit. |
| `500` | Internal Server Error | An unexpected error occurred on the platform. |


## Error response body

All error responses share the same JSON shape. The top-level public fields are
`errorCode`, `errorMessage`, and `requestId`:

```json
{
  "errorCode": "MESSAGE_NOT_FOUND",
  "errorMessage": "Message not found or not yet available.",
  "requestId": "req_123"
}
```

`errorCode` is a stable, machine-readable identifier you can branch on, while
`errorMessage` is a human-readable description that may change over time.
Always rely on `errorCode` (and the HTTP status) rather than parsing
`errorMessage`.

Common `errorCode` values:

| `errorCode` | Typical status |
|  --- | --- |
| `VALIDATION_ERROR` | `400` |
| `INVALID_REQUEST_BODY` | `400` |
| `UNAUTHORIZED` | `401` |
| `FORBIDDEN` | `403` |
| `MESSAGE_NOT_FOUND` | `404` |
| `PAYLOAD_TOO_LARGE` | `413` |
| `RATE_LIMITED` | `429` |
| `INTERNAL_ERROR` | `500` |


### Validation errors

For `400` validation failures, the response adds an `errors` array with one
detail object per problem. Each detail carries a human-readable `message` and,
when known, the `field` it applies to:

```json
{
  "errorCode": "VALIDATION_ERROR",
  "errorMessage": "Request rejected. Validation errors found.",
  "requestId": "req_123",
  "errors": [
    { "field": "body", "message": "Missing required field 'body'" }
  ]
}
```

## Next steps

- [Authentication](/docs/api/authentication) — Bearer token details.
- [Rate limits](/docs/api/rate-limits) — throttling and `429` behavior.