Error Codes
Reference for all error codes returned by the HookSniff API.
Error Response Format
All errors follow a consistent JSON structure:
{
"error": {
"code": "BAD_REQUEST",
"message": "Invalid request body or parameters"
}
}The code field is a machine-readable identifier. The message field is a human-readable description.
HTTP Status Codes
| Status | Code | Meaning | Common Cause |
|---|---|---|---|
| 400 | BAD_REQUEST | Bad Request | Invalid JSON, missing required fields, or validation failure |
| 401 | UNAUTHORIZED | Unauthorized | Missing or invalid API key, expired JWT token |
| 403 | FORBIDDEN | Forbidden | Insufficient permissions, plan limit exceeded, or admin-only endpoint |
| 404 | NOT_FOUND | Not Found | Resource doesn't exist or doesn't belong to your account |
| 409 | CONFLICT | Conflict | Duplicate resource, idempotency key collision |
| 413 | PAYLOAD_TOO_LARGE | Payload Too Large | Request body exceeds 1 MB limit |
| 429 | RATE_LIMIT_EXCEEDED | Rate Limited | Too many requests β check Retry-After header |
| 500 | INTERNAL_ERROR | Internal Server Error | Unexpected error β contact support if persistent |
Common Errors and Solutions
401 UNAUTHORIZED
Your API key is missing, invalid, or expired.
Fix: Check that your Authorization header is Bearer hr_live_... and the key is active in your dashboard settings.
400 BAD_REQUEST β Invalid endpoint_id
The endpoint ID doesn't exist or doesn't belong to your account.
Fix: List your endpoints with GET /v1/endpoints and use a valid ID.
429 RATE_LIMIT_EXCEEDED
You've exceeded your plan's requests-per-minute limit.
Fix: Wait for the Retry-After header duration, then retry with exponential backoff. Consider upgrading your plan if this happens frequently.
403 FORBIDDEN β Webhook limit exceeded
You've reached your plan's monthly webhook limit.
Fix: Check usage with GET /v1/billing/usage. Upgrade your plan or wait for the next billing period.
413 PAYLOAD_TOO_LARGE
The webhook payload exceeds the 1 MB limit.
Fix: Reduce payload size. Send only essential data. If you need to send large payloads, consider uploading to storage and including a URL in the webhook.
Idempotency Errors
When using the Idempotency-Key header:
- If the same key is used within 24 hours, the cached response is returned (not an error)
- If the same key is used with different parameters, a 409 CONFLICT is returned
- Keys expire after 24 hours and can be safely reused