Errors

CHIP Collect returns errors in two places:

HTTP responses to your API requests. Errors come back as 4xx (client errors) or 5xx (server errors) with a JSON body containing a code and a human-readable message.
Webhook events for things that happen after the initial request, such as purchase.payment_failure with an error_code field in the payload.

This page lists the most common codes and the recommended next step. Always log the full response so you can debug from the raw error.

HTTP error responses

Status	`code`	Meaning	Recommended action
400	`invalid_request`	One or more required fields are missing or malformed.	Inspect the `message` field for the offending field. Validate inputs client-side before sending.
400	`invalid_recurring_token`	The recurring token is unknown, revoked, or expired.	Re-prompt the buyer for a new card. Do not retry the charge.
401	`unauthorized`	API key is missing, malformed, or invalid.	Verify the `Authorization` header is `Bearer <secret_key>` and the key is from the right brand.
403	`forbidden`	The API key does not have access to this resource.	Confirm the key has the required scopes in the merchant portal.
404	`not_found`	The purchase, client, or webhook does not exist.	Double-check the ID. Records in CHIP Collect are not deleted by default.
409	`conflict`	The operation is not valid for the resource’s current state.	Inspect the resource’s `status` field. For example, you cannot capture an already-captured purchase.
422	`unprocessable_entity`	The request is well-formed but semantically invalid.	Read the `message` field. Common cause: amount exceeds the remaining capturable balance.
429	`rate_limited`	Too many requests in a short window.	Back off and retry with jitter. Honor any `Retry-After` header if present.
500	`internal_error`	Something went wrong on CHIP’s side.	Safe to retry with idempotency. If it persists, contact support@chip-in.asia.
502	`bad_gateway`	Upstream provider (bank, card network) returned an error.	Do not retry immediately. Wait for the corresponding webhook before acting.
503	`service_unavailable`	Planned maintenance or temporary outage.	Retry with exponential backoff. Status page: https://status.chip-in.asia (if available).

Webhook `error_code` values

These appear on purchase.payment_failure and purchase.cancelled events.

`error_code`	Meaning	Recommended action
`insufficient_funds`	The buyer’s account did not have enough funds at the time of payment.	Ask the buyer to use a different payment method. Do not auto-retry.
`payment_declined`	The buyer’s bank or card issuer declined the transaction.	Ask the buyer to contact their bank or use a different method.
`payment_cancelled`	The buyer explicitly cancelled the payment on the bank or card page.	Treat as a soft decline. Allow the buyer to retry.
`payment_expired`	The buyer did not complete payment within the expiry window.	Issue a new purchase if the buyer still wants to pay.
`invalid_signature`	(Only when re-validating locally) The webhook signature could not verify.	Check that you are reading the raw request body and using the public key for the right webhook.
`invalid_recurring_token`	The recurring token has been deleted or revoked.	Re-prompt the buyer to enrol a new card.

Idempotency

For write operations (create, charge, capture, refund, etc.), the same request body sent twice with the same Idempotency-Key header will return the same result without performing the action twice. Always generate an Idempotency-Key server-side for non-idempotent operations so a network retry does not create duplicates.

When to contact support

Open a ticket to support@chip-in.asia if:

The same error code is returned for more than 1% of your traffic.
You receive an HTTP 5xx response that retries do not clear.
A webhook event_id is not delivered within 5 minutes of the corresponding purchase.paid event.

Always include the purchase_id, the request timestamp, and the full response body.

Overview

Integrate with AI agents

API Reference

HTTP error responses

Webhook `error_code` values

Idempotency

When to contact support

​HTTP error responses

​Webhook error_code values

​Idempotency

​When to contact support

HTTP error responses

Webhook `error_code` values

Idempotency

When to contact support