> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hookstream.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

Standard error response format and common HTTP status codes.

All hookstream API errors return a consistent JSON format with an error message, HTTP status code, and a unique `request_id` for debugging. Provide the `request_id` to hookstream support when investigating issues.

## Error response format

Every error response includes three fields:

**error**

Human-readable error message.

**status**

HTTP status code.

**request_id**

Unique identifier for the request. Provide this to support.

```json 404 Not Found
{
  "error": "Source not found",
  "status": 404,
  "request_id": "req_a1b2c3d4e5f6"
}
```

## Status codes

| Status | Meaning | Common causes |
| --- | --- | --- |
| `400` | Bad Request | Invalid body, missing fields, malformed parameters. |
| `401` | Unauthorized | Missing or invalid API key / session cookie. |
| `403` | Forbidden | Valid auth but insufficient permissions, or IP blocked. |
| `404` | Not Found | Resource doesn't exist or belongs to a different org. |
| `409` | Conflict | Duplicate resource, or event deduplicated at ingest. |
| `429` | Too Many Requests | Rate limit or plan quota exceeded. |
| `500` | Internal Server Error | Unexpected server error. |

## Common errors

**400 Bad Request**

The request body was invalid. Check that all required fields are present, types match, and JSON is well-formed. The `error` field will describe which field failed validation.

    ```json
    {
      "error": "Invalid body: 'slug' must match pattern ^[a-z0-9-]+$",
      "status": 400,
      "request_id": "req_..."
    }
    ```
  **401 Unauthorized**

Your API key is missing, invalid, or the session cookie has expired. Check that you are sending `X-API-Key: hs_live_...` or that your session is valid.

    ```json
    { "error": "Invalid API key", "status": 401, "request_id": "req_..." }
    ```
  **403 Forbidden**

The authenticated user does not have permission to access the resource, or a source's IP allowlist/denylist has blocked the request.

    ```json
    { "error": "Forbidden", "status": 403, "request_id": "req_..." }
    ```
  **404 Not Found**

The resource does not exist, or it belongs to a different organization/project. Verify the ID and that you are using the correct API key for the right project.

    ```json
    { "error": "Source not found", "status": 404, "request_id": "req_..." }
    ```
  **409 Conflict**

For ingestion, this means the event was deduplicated — the same payload hash or dedup key was already seen. For resource creation, a resource with the same slug or unique field already exists.
  **429 Too Many Requests**

You've exceeded a rate limit or your plan's monthly quota. Check the [`RateLimit-*` response headers](/api/pagination-rate-limits#rate-limit-headers) and retry after the reset time. Paid plans have a soft limit — events are accepted up to 120% before returning 429. The Free plan hard-caps at 100%.
  **500 Internal Server Error**

An unexpected error occurred on the server. Retry the request with exponential backoff. If the error persists, contact support with the `request_id` so we can investigate.

## Related

**[Authentication](/api/authentication)**

Troubleshoot 401 errors.
  **[Pagination & rate limits](/api/pagination-rate-limits)**

Handle 429 errors.