Catch Errors
All errors return JSON with error, code, and optional fields.
Common errors
| Code | Status | Cause | Fix |
|---|---|---|---|
validation_error | 400 | Invalid request body or parameters | Check fields in the response |
unauthorized | 401 | Missing or invalid API key | Add Authorization: Bearer sm_.... See Authentication |
forbidden | 403 | Authenticated but not authorized | Verify you own the bucket |
not_found | 404 | Resource does not exist | Check bucket or event ID |
rate_limit_exceeded | 429 | Too many requests | Back off and retry. See Rate Limits |
Catch-specific errors
| Code | Status | Cause | Fix |
|---|---|---|---|
catch.bucket_not_found | 404 | Bucket does not exist or you lack access | Verify bucket ID with GET /v1/catch/buckets |
catch.event_not_found | 404 | Event does not exist in this bucket | Events expire per retention policy |
catch.signature_invalid | 400 | Signature verification failed | Verify signing secret matches provider |
catch.provider_unsupported | 400 | Provider not recognized | Use stripe, github, shopify, or svix |
catch.replay_failed | 500 | Could not deliver to target URL | Verify target_url is reachable and accepts POST |
bucket_limit_exceeded | 403 | Tier bucket limit reached | Delete unused buckets or upgrade |
bucket_paused | 400 | Replay attempted on paused bucket | Set bucket to live via PATCH /v1/catch/buckets/:id |
Signature verification tips
- Stripe: Secret starts with
whsec_. Get from Dashboard > Developers > Webhooks. - GitHub: Uses
X-Hub-Signature-256. Secret must match exactly (no trailing whitespace). - Shopify: Uses
X-Shopify-Hmac-Sha256. Secret is base64 encoded. - Svix: Secret starts with
whsec_. Supports multiple signatures for key rotation.
For detailed debugging, see Troubleshooting.