AI resources
Possible errors
When integrating Split Payments 1:N, the API may return validation errors with specific codes and messages. Below are the errors by topic and the response format.
All validations run in sequence; the first validation that fails stops the process.
Error code mapping
Errors use base types that map to HTTP status codes:
| Base error type | HTTP status code | Description |
| TypeErrorClient | 400 | Bad Request. Client errors with specific messages for fixable issues. |
| TypeErrorInvalidInput | 400 | Bad Request. Invalid input data. |
| TypeErrorUnprocessable | 422 | Unprocessable Entity. Validation errors (user validation, compliance validation). Used to distinguish from client errors (400). |
| TypeErrorNotFound | 404 | Not Found. Resource not found. |
| TypeErrorInternal | 500 | Internal Server Error. Server-side errors. |
| TypeErrorUnavailable | 503 | Service Unavailable. Returned when external services (User Search, KYC) are unavailable. |
Receiver validations
Validations related to receivers (sellers) in the split.
| Validation name | Error code | HTTP status | Error message | Description |
| Missing primary receiver | TypeErrorClient | 400 | "primary receiver must be present in the split" | At least one receiver must be marked as primary (usually the seller who started the split). The primary receiver (primary seller) is the owner of the application used in the integration. |
| Minimum secondary receivers | TypeErrorClient | 400 | "minimum of 1 secondary receiver is required" | At least one secondary receiver is required. |
| Duplicate receivers | TypeErrorClient | 400 | "there are users duplicated" | No user ID may appear more than once in the receiver list. |
| Seller limit exceeded | TypeErrorClient | 400 | "split contains more sellers than allowed" | The total number of receivers cannot exceed the configured maximum (when MaxSplitSellers is configured). The maximum allowed is 10 secondary sellers per order. |
Amount validations
Validations for split amounts. Some apply only to percentage splits and others only to fixed splits.
| Validation name | Error code | HTTP status | Error message | Description |
| Invalid percentage range | TypeErrorClient | 400 | "percentage must be between 1 and 100" | Each receiver's percentage must be between 1 and 100 (percentage splits only). |
| Invalid percentage sum | TypeErrorClient | 400 | "percentages must add up to 100.00" | The sum of all receiver percentages must be exactly 100.00 (percentage splits only). |
| Invalid fixed amount sum | TypeErrorClient | 400 | "the sum of the amounts for the receivers must be equal to the total amount of the split" | The sum of all receiver amounts must equal the total split amount (fixed splits only). |
Payment validations
Validations that apply to payment methods.
| Validation name | Error code | HTTP status | Error message | Description |
| Invalid payment method type | TypeErrorClient | 400 | "invalid payment method type" | The payment method type must be in the allowed list configured in the system. Allowed payment methods are credit card and debit card. |
Item validations
Validations that only apply when the split includes items.
| Validation name | Error code | HTTP status | Error message | Description |
| Duplicate item external codes | TypeErrorClient | 400 | "items list contains duplicate external code" | There cannot be two items with the same external_code. |
| Invalid item reference | TypeErrorClient | 400 | "receiver references non-existent item" | All item references in receivers must match items that exist in the split. |
User validations
External validations performed against the User Search service.
| Validation name | Error code | HTTP status | Error message | Description |
| User not found | TypeErrorUnprocessable | 422 | "user validation error" | The user ID does not exist in the system (the user service returns 404). |
| User not active | TypeErrorUnprocessable | 422 | "user validation error" | The user exists but is not in "active" status (guest, deactive, pending or empty status). |
| User site mismatch | TypeErrorUnprocessable | 422 | "user validation error" | The user's site ID does not match the seller's site ID. |
| User service unavailable | TypeErrorUnavailable | 503 | "service unavailable" | Network errors or timeout when calling the user service. |
| Seller using PNF mode | TypeErrorUnprocessable | 422 | "seller is using pnf mode, blocked" | The transaction is blocked if the seller is operating in PNF mode (Payment Not in Flow). |
KYC compliance validations
External validations performed against the KYC Compliance service.
| Validation name | Error code | HTTP status | Error message | Description |
| KYC compliance verification failure | TypeErrorUnprocessable | 422 | "compliance validation error" | The user is not compliant (status is not "compliant" or "skip_compliance"). |
| KYC service unavailable | TypeErrorUnavailable | 503 | "service unavailable" | Network errors or timeout when calling the KYC service. |
Internal errors
| Validation name | Error code | HTTP status | Error message | Description |
| Internal server error | TypeErrorInternal | 500 | "internal server error" | Unexpected server-side error. |
Error response format
Errors return in the following format, with the errors field as an array (it may be empty when the error context is described in the main message):
Client error (400)
json
{ "status": 400, "message": "percentages must add up to 100.00", "errors": [] }
Validation error (422)
json
{ "status": 422, "message": "user validation error", "errors": [] }
Service unavailable (503)
json
{ "status": 503, "message": "service unavailable", "errors": [] }
Internal error (500)
json
{ "status": 500, "message": "internal server error", "errors": [] }