Error Codes
The HookWatch API uses standard HTTP status codes to indicate success or failure. This page documents all error codes and how to handle them.
Error Response Format
All error responses follow this structure:
Json
HTTP Status Codes
Success Codes
| Code | Name | Description |
|---|---|---|
200 | OK | Request succeeded |
201 | Created | Resource created successfully |
204 | No Content | Request succeeded, no content returned (e.g., delete) |
Client Error Codes
| Code | Name | Description |
|---|---|---|
400 | Bad Request | Invalid request body, missing required fields, or malformed JSON |
401 | Unauthorized | Missing, invalid, or expired authentication token |
403 | Forbidden | Authenticated but not allowed (plan limits, permissions) |
404 | Not Found | Resource doesn't exist or you don't have access |
409 | Conflict | Resource already exists or action conflicts with current state |
422 | Unprocessable Entity | Request was valid but cannot be processed (business logic error) |
429 | Too Many Requests | Rate limit exceeded. Check Retry-After header |
Server Error Codes
| Code | Name | Description |
|---|---|---|
500 | Internal Server Error | Something went wrong on our end. Try again or contact support |
502 | Bad Gateway | Upstream service unavailable. Usually temporary |
503 | Service Unavailable | Service temporarily unavailable (maintenance or overload) |
Error Codes
The error.code field provides a machine-readable error type:
| Code | Description |
|---|---|
validation_error | Request failed validation. Check details array for specific fields |
authentication_required | No authentication provided |
invalid_token | Token is malformed or invalid |
token_expired | Token has expired. Refresh or re-authenticate |
resource_not_found | The requested resource doesn't exist |
resource_exists | Resource already exists (duplicate) |
plan_limit_reached | You've reached a limit of your current plan |
rate_limited | Too many requests. Slow down |
internal_error | Unexpected server error |
Handling Errors
- 401: Refresh your access token and retry the request
- 429: Wait for the time specified in Retry-After header
- 5xx: Retry with exponential backoff
- 400/422: Fix the request based on error details