Error Handling

Why You Would Use This

When an API request fails, HookBridge returns a structured error response. Understanding the format and common error codes helps you build robust integrations that handle failures gracefully.

Error Response Format

All error responses follow the same structure:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description of the problem.",
    "details": {}
  },
  "meta": {
    "request_id": "req_abc123"
  }
}

• error.code — a machine-readable string you can match on.
• error.message — a human-readable explanation.
• error.details — optional object with additional context (varies by error).
• meta.request_id — unique identifier for the request, useful for support inquiries.

HTTP Status Codes

Status	Meaning
400	Bad request — invalid input, missing required fields, or validation failure.
401	Unauthorized — missing, invalid, or inactive API key.
403	Forbidden — access denied or plan restriction.
404	Not found — the requested resource does not exist.
409	Conflict — duplicate resource, idempotency mismatch, or state conflict.
410	Gone — payload retention expired or export link expired.
429	Too many requests — rate limit or usage quota exceeded.
500	Internal server error — unexpected failure.

Common Error Codes

Authentication

Code	Status	Description
UNAUTHORIZED	401	Missing or invalid API key, or expired session.
RATE_LIMITED	429	Too many failed authentication attempts.
FORBIDDEN	403	Access denied to the requested project.

Validation

Code	Status	Description
INVALID_REQUEST	400	Invalid JSON, missing required fields, or general validation error.
INVALID_ENDPOINT	400	Endpoint URL is invalid — not HTTPS, too short/long, or targets a blocked address.
PAYLOAD_TOO_LARGE	400	Payload exceeds the 1 MB size limit.

Endpoints

Code	Status	Description
DUPLICATE_URL	409	An endpoint with this URL already exists in the project.
ENDPOINT_BLOCKED	400	Endpoint URL targets a private or internal address.
ENDPOINT_UNREACHABLE	400	Endpoint domain could not be resolved.

Idempotency

Code	Status	Description
IDEMPOTENCY_MISMATCH	409	Same idempotency key sent with a different payload.
IDEMPOTENCY_CONFLICT	409	Duplicate idempotency key with conflicting request.

Signing Keys

Code	Status	Description
MAX_SIGNING_KEYS_REACHED	409	Endpoint already has the maximum number of signing keys.
CANNOT_DELETE_LAST_SIGNING_KEY	409	Cannot delete the only remaining signing key.

Retention & Payload

Code	Status	Description
RETENTION_EXPIRED	410	Message payload retention period has expired and the payload is no longer available.
PAYLOAD_UNAVAILABLE	410	Message payload has been cleaned up and cannot be replayed.

Rate Limits & Quotas

Code	Status	Description
BURST_LIMIT_EXCEEDED	429	Project-level request rate exceeded. Includes retry_after_ms in details.
USAGE_LIMIT_EXCEEDED	429	Monthly message limit exceeded. Includes plan, usage, limit, and resets in details.
ENDPOINT_LIMIT_REACHED	429	Maximum endpoints for your plan reached.
PROJECT_LIMIT_REACHED	429	Maximum projects for your plan reached.
KEY_LIMIT_EXCEEDED	429	Maximum API keys per project reached.
EXPORT_LIMIT_EXCEEDED	429	Export rate limit or concurrency limit reached.
REPLAY_LIMIT_EXCEEDED	429	Replay batch size or frequency limit exceeded.

Billing

Code	Status	Description
NO_SUBSCRIPTION	404	No active subscription found.
ALREADY_SUBSCRIBED	409	Tenant already has an active paid subscription.
SUBSCRIPTION_INACTIVE	403	Subscription is past due, canceled, or unpaid.
PLAN_REQUIRED	403	Feature requires a higher-tier plan.

Exports

Code	Status	Description
EXPORT_ACTIVE	409	Cannot delete an export that is still in progress.
EXPORT_NOT_READY	400	Export is not yet ready for download.
EXPORT_EXPIRED	410	Export download link has expired.

Handling Errors

• Match on error.code for programmatic handling, not error.message (messages may change).
• For 429 responses, check error.details.retry_after_ms and wait before retrying.
• Include the meta.request_id when contacting support about a specific failure.
• 5xx errors are transient — retry with backoff.
• 4xx errors require fixing the request before retrying (except 429, which is a temporary rate limit).