This document details Tillo's API error codes across versions 1 and 2, categorizing them into authentication, validation, brand relationship, gift card transactions, balance, system, feature availability, and general HTTP errors. It explains common causes like missing permissions or insufficient balance, provides specific error codes with HTTP statuses, retryability, descriptions, and examples, and advises on troubleshooting and support contact requirements.
🌟 This list of API errors is pulled directly from our API documentation here: https://tillo.tech/error_codes/
Note: These error codes are consistent across version 1 and 2 of our API (v2 introduced some additional error cases)
An error does not always mean something is broken. Many errors are expected guardrails, such as missing permissions, a feature not enabled, or insufficient balance/credit.
First step is to determine what type of error you are getting. Using the codes below you may be able to trouble shoot the issue on your own, or by comparing the brand details page (see: Utilizing the Brand Details Page).
Authentication & Authorization Errors
Failures that mean the request is not trusted or not allowed.
- Invalid or missing API key.
- Key is valid but does not have access to that environment, endpoint, brand, or feature.
- IP is not on the allowlist.
- The account or user is disabled, locked, or lacks the required role.
| Code | HTTP | Retryable | Description | Example |
|---|---|---|---|---|
| 060 | 400 | No | API v1 only - invalid or expired API Token | Token mismatch error |
| 210 | 401 | No | Invalid IP address | Invalid IP address |
| 434 | 404 | No | Authentication failed | Authentication failed |
| 706 | 401 | No | Sale is disabled | Brand [Amazon Fr] is not available through the API |
| 717 | 401 | No | The partner does not have access to the template for the requested brand | Template for brand [Amazon FR] is not available for this partner |
Validation Errors
Failures caused by the request payload being incomplete or incorrectly formatted.
- Missing required fields.
- Wrong data types, invalid dates, invalid currency codes, or malformed JSON.
- Values outside allowed ranges.
- Business rules not met (for example, conflicting fields or invalid combinations).
| Code | HTTP | Retryable | Description | Example |
|---|---|---|---|---|
| 070 | 400 | No | Missing parameters | Missing parameter [personalisation] |
| 070 | 400 | No | Missing parameter [amount] | There were errors validating the request |
| 071 | 400 | No | API v1 only - Missing additionalParams | Missing parameter [additionalParams] |
| 433 | 422 | No | Validation Errors | There were errors validating the request |
| 704 | 422 | No | The [amount] must be a number | There were errors validating the request |
| 704 | 400 | No | Invalid value | There were errors validating the request |
| 704 | 500 | No | Invalid value | Denomination [5.00] not available for Brand [Gap] |
| 704 | 400 | No | Invalid value | Denomination [5.00] not available for Brand [Gap] |
| 704 | 400 | No | Invalid value | The sector [sales] is invalid. Please provide an acceptable one |
| 704 | 400 | No | Invalid value | There were errors validating the request: The requested face value [5.123] is invalid. The face value must have a maximum of 2 Decimal Places |
| 712 | 404 | No | Delivery method not found | The requested delivery method was not found |
| 713 | 400 | No | The delivery method is not allowed | You cannot deliver codes via [url] for [Adidas] |
| 714 | 400 | No | You did not supply a delivery method and we were unable to fallback to the default | There were errors validating the request |
| 716 | 400 | No | The requested template was not found | The requested template was not found |
| 719 | 422 | No | The transaction type is not supported by the partner | The transaction type is not supported by the partner |
| 720 | 422 | No | The transaction type is not supported for the requested brand | The transaction type is not available for the requested brand |
| 721 | 422 | No | The currency iso code was not found | The requested currency was not found |
| 722 | 400 | No | The currency iso code was not supplied | You did not supply a currency |
| 723 | 422 | No | The requested currency iso code is not supported by this brand | The requested currency is not supported by this brand |
| 730 | 400 | No | Invalid sale reference | Invalid sale uuid for gift code look up |
| 731 | 400 | No | Sale reference not supplied | You did not supply a sale reference |
| 738 | 422 | No | The currency requested can only be used with the International Payments feature | The requested currency [GBP] is only available with International Payments |
| 739 | 422 | No | The brand requested is not supported by International Payments (e.g. a Choice Link brand) | The requested brand [amazon] is not supported by International Payments |
| 740 | 400 | No | The requested feature is only available through API v2 | The requested feature is only available through API v2 |
Brand & Relationship Errors
Failures related to brand setup and who is allowed to transact with whom.
- Brand is not enabled for the buyer.
- Buyer is not approved for the brand.
- Brand is disabled temporarily due to an incident, compliance, or operational controls.
- Relationship exists, but the requested product, currency, or region is not supported.
| Code | HTTP | Retryable | Description | Example |
|---|---|---|---|---|
| 072 | 400 | No | Brand not found | The requested brand [great-british-pub] does not exist |
| 072 | 400 | No | Invalid brand | Brand [tesco] is not available for this partner |
| 072 | 401 | No | Invalid brand for this partner | Brand [Gb Pub] is not available for this partner |
| 709 | 404 | No | A relationship between the Partner and the Brand does not exist | We couldn't find a record for a relationship between yourself and brand [Debenhams UK] |
Gift Card & Transaction Errors
Failures during issuance, redemption, cancellation, refund, or status retrieval.
- The code cannot be issued due to brand-side rules, product constraints, or stock issues.
- The code is not found, already redeemed, expired, or already refunded.
- Duplicate transaction attempts, idempotency conflicts, or replayed requests.
- Transaction state does not allow the requested action (for example, trying to refund a transaction that is not eligible).
| Code | HTTP | Retryable | Description | Example |
|---|---|---|---|---|
| 100 | 422 | No | The gift code has already been cancelled | The gift code has already been cancelled |
| 100 | 422 | No | Attempting to cancel a gift code that was not issued successfully | Attempting to cancel a gift code that was not issued successfully |
| 100 | 422 | No | Error | Error |
| 708 | 400 | No | The original request failed. Please re-submit with a new clientRequestID | The original request failed. Please re-submit with a new clientRequestID |
| 708 | 400 | No | The clientRequestID already exists however the brand and value supplied do not match. If you ARE trying to replay a request please ensure that the brand and value match too, or please re-submit the request with a new clientRequestID to generate a new giftcard | The clientRequestID already exists however the brand and value supplied do not match. If you ARE trying to replay a request please ensure that the brand and value match too, or please re-submit the request with a new clientRequestID to generate a new giftcard |
| 711 | 400 | No | Cancel not active | Card no longer active |
| 724 | 422 | No | The sale reference provided cannot be found on our system | The sale could not be found |
| 728 | 403 | No | Insufficient balance on card | Insufficient balance on card |
| 729 | 400 | Yes | Duplicate request incomplete | The original request is still being processed. Please try again later |
| 736 | 400 | No | Invalid financial relationship | Cannot fulfil order, invalid financial relationship |
Balance & Credit Errors
Failures because there is not enough available funding to complete the action.
- Insufficient balance for the partner or brand account.
- Insufficient credit with the brand company.
- Credit account is paused or restricted.
- Funds are available in one place, but the specific balance type required for the request is not available.
| Code | HTTP | Retryable | Description | Example |
|---|---|---|---|---|
| 610 | 403 | No | Insufficient Monies on account balance on account for Partner, Brand Company or Brand | Insufficient balance on account |
| 610 | 422 | No | Insufficient Monies on account balance on account for Partner, Brand Company or Brand | Insufficient balance on account |
| 615 | 403 | No | Insufficient credit with Brand company | Insufficient credit with [Mitchells & Butlers] |
| 615 | 422 | No | Insufficient credit with Brand company or Brand | Insufficient credit with [Mitchells & Butlers] |
| 616 | 422 | No | Credit account with Tillo is paused | The credit account with Tillo is PAUSED, contact the Finance Team |
System & Service Errors (Retryable)
Temporary failures where retrying later may succeed.
- Internal server error.
- Timeouts or upstream dependency failures.
- Intermittent outages, maintenance windows, or transient network issues.
- Rate limiting or throttling. If present, retries should use backoff.
| Code | HTTP | Retryable | Description | Example |
|---|---|---|---|---|
| 600 | 500 | Yes | Internal error | Internal error |
| 602 | 500 | Yes | System unavailable due to maintenance | Internal error |
| 603 | 500 | Yes | External – Issue communicating with the Processor | Service unavailable for brand [amazon] |
| 604 | 503 | Yes | Health Check | Error |
| 715 | 503 | Yes | The URL hosting service is currently unavailable | The URL hosting service is currently unavailable |
| 725 | 500 | Yes | The requested denominations is not in stock | Denomination [10.00] is currently not in stock for Brand [Gap] |
Feature & Service Availability Errors
Failures because the capability is not enabled for the account or is not available in the current context.
- A required feature flag is not enabled.
- Feature is enabled in production but not in sandbox, or vice versa.
- Feature is restricted to certain roles or partner types.
- The request is attempting to use a feature that is not supported for the brand.
| Code | HTTP | Retryable | Description | Example |
|---|---|---|---|---|
| 726 | 503 | No | A required feature has not been enabled | The requested feature [tagging] is not enabled for you |
General HTTP Errors
Broad transport and protocol failures that point to “where” the issue is, not always “why.”
| Code | HTTP | Retryable | Description | Example |
|---|---|---|---|---|
| 999 | 404 | No | The requested endpoint was not found | Not Found |
| 999 | 405 | No | The requested method is not allowed | Method not allowed |
| 999 | 500 | Yes | Internal error | Internal error |
Success Codes
| Code | HTTP | Retryable | Description | Example |
|---|---|---|---|---|
| 000 | 200 | N/A | Success | Success |
✉️ Reaching out for support (email servicedesk@tillo.io)
please include the following in your support request. This helps our engineers see exactly what the API is seeing:
The API Endpoint: (e.g., GET, POST, and the specific URL)
The Raw Signature String: Before it’s been hashed.
The Hashed Signature String: The final version sent in the request.
Request Headers: To check your authentication keys and content types.
Full Request Body: The exact JSON or data payload.
Client Request ID: If you have one logged on your end.
Timestamp: The exact time the request was made.
Comments
0 comments
Please sign in to leave a comment.