Errors & Troubleshooting
TabEdge Checkout APIs use HTTP status codes and JSON error responses. Always check the HTTP status before processing a response.
HTTP Error Reference
| Status | Meaning | Recommended Action |
|---|---|---|
| 400 | Bad Request | Check amountCents, currency, description, redirect URLs, merchantReference, and checkout ID. |
| 401 | Unauthorized | Check the Bearer API key, format, revocation status, Business binding, and environment. |
| 403 | Forbidden | The checkout does not belong to the authenticated Business, owner, or environment. |
| 404 | Not Found | The requested checkout session does not exist. |
| 409 | Conflict | Check Business payment readiness, API key environment, and allowed redirect domains. |
| 500 | Internal Server Error | An unexpected server error occurred. Retry cautiously and contact support if persistent. |
These codes describe the verified Checkout Creation and Checkout Status endpoints. Other TabEdge APIs may differ.
Error Response Format
Most errors contain an error string. Some responses include additional code or reason fields. Do not assume that every error has the same optional fields.
Example: Invalid Currency — HTTP 400
{
"error": "currency must be \"usd\"."
}Example: Business Not Payment-Ready — HTTP 409
{
"error": "business_not_payment_ready",
"reason": "EXAMPLE_REASON"
}EXAMPLE_REASON is illustrative; the actual reason depends on the Business readiness evaluation.
Example: Redirect Domains Missing — HTTP 409
{
"error": "No allowed redirect domains are configured for this Business.",
"code": "ALLOWED_REDIRECT_DOMAINS_REQUIRED"
}Troubleshooting
- 401: Confirm your backend sends the correct Business-scoped API key in the Authorization Bearer header.
- 400: Ensure amountCents is a positive integer, currency is usd, and redirect URLs use authorized domains.
- 403: Use the API key belonging to the Business that created the checkout.
- 404: Confirm the checkoutId was saved correctly.
- 409: Check Business onboarding, payment readiness, environment, and Developer Settings.
- 500: Do not blindly create another checkout. First check whether the original request created a session. Escalate persistent errors to TabEdge Support.
Safe Retry Practices
Do not automatically retry every error. Correct validation, authentication, and configuration errors before retrying. A network failure or server error does not prove that a checkout creation request failed before saving data. Reconcile the order on your backend before creating a new checkout to avoid duplicate sessions.