4. Error handling

4.1 Do you offer webhooks for refund status changes?

Yes. Webhooks are available for refund status changes, covering two event types:

• refund_request.status_updated: fires on status changes during the quote stage. The failure value on this event is ERROR_PROCESSING_REQUEST, not ERROR.
• refund_candidate.status_updated: fires on refund candidate status changes, including but not limited to the terminal states REFUNDED and ERROR. Deliveries also occur for non-terminal changes such as READY and REVIEW.

Events are delivered to a client-configured endpoint URL. See the Webhooks guide for setup, payloads, and verification, and the Webhook API Reference for status values and configuration API.

4.2 How do I subscribe, verify events, and handle retries?

Clients configure their own webhook endpoints and event subscriptions; via the Dashboard or the addWebhookEvent / deleteWebhookEvent / rollWebhookSecret mutations in the Webhook API Reference, and are responsible for verifying incoming signatures (HMAC or API key). See the Webhooks guide for the delivery contract (retry attempts, intervals, timeouts, payload limits) and verification steps.

4.3 What error codes should I expect, and how do I interpret them?

• Authentication error (expired token): calls fail with an auth error; refresh the token.
• Validation error (missing required data): mutation returns descriptive validation errors (e.g., missing email).
• Resource not found: may return null or an error object with details.
• Duplicate record: attempting to create a unique value that already exists returns a duplicate error.
• Sync quote timeout (createQuote with Sync: true): an item may return error: "Failed due to timeout" and message: "Quote result timeout, call query document."; not a definitive failure; call document(ticketNum) (or wait for the quote-stage webhook). Details: Request parameters.

Most error messages are explicit and help identify whether the issue is authentication, validation, missing resources, or duplicates.

4.4 Are there rate or concurrency limits, and how should I handle 429 responses?

There is no global public rate limit. Internally, throughput is calibrated to each client’s expected volume. In rare cases of excess, the API may return HTTP 429. Implement standard backoff and retry where appropriate.