Errors, limits, and pagination
Handle actual response status and endpoint-specific list and throttling behavior.
Diagnose the response
Read the HTTP status together with the actual error body. Do not treat a generic status as a complete diagnosis.
| Status | What to investigate |
|---|---|
| 400 | Invalid fields, missing external IDs, or unsupported event |
| 401 | Missing/invalid key or signature, expired credentials or timestamp |
| 403 | Business permission, missing/inactive integration, or unavailable feature |
| 404 | Wrong business-scoped record or unknown external product/variant |
| 429 | Request throttling; slow the client and honor Retry-After if returned |
| 5xx | Server/provider failure; inspect result before retrying side effects |
Rate limits
The inspected backend configures global throttle defaults of 10 requests per second, 50 per 10 seconds, and 200 per minute. These are source defaults, not per-plan allowances or a guarantee for every deployed route. Route overrides, proxy behavior, and provider limits can differ. Inspect the deployed response and use bounded backoff; do not retry writes blindly after an ambiguous failure.
Pagination is endpoint-specific
The external product bootstrap/sync POST APIs do not paginate. The dashboard's integration webhook-delivery list accepts limit, offset, and an optional event filter at:
GET /api/v1/businesses/:businessId/integrations/:integrationId/webhooks/:webhookId/deliveries
?limit=20&offset=0
This is an authenticated management route, not an assertion that an external product API key can read dashboard delivery logs. Other inbox APIs may use page/limit and hasMore instead. Do not apply one list's pagination shape to another endpoint.
Partial results and recovery
Bootstrap returns per-record failures even when the request itself succeeds. Inspect failed, correct those records, and verify the existing catalog before replay. For webhook transport failures inspect actual deliveries; see signature and delivery behavior. Keep secrets and unnecessary customer content out of diagnostic logs.
Expected result
Your client preserves the real error, handles the endpoint's own list contract, and avoids duplicate business actions while recovering.
Developer reference and contract boundaries
Inspect supported integration metadata and distinguish dashboard operations from external APIs.
External product API
Bootstrap and synchronize an externally owned catalog with verified request examples.
Integration authentication and webhook signatures
Use API keys or timestamped HMAC and distinguish inbound and outbound secrets.