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:
Human-readable error message.
HTTP status code.
Unique identifier for the request. Provide this to support.
json{ "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
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_..." }
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_..." }
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_..." }
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_..." }
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.
You've exceeded a rate limit or your plan's monthly quota. Check the RateLimit-* response 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%.
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.