# MD for: https://www.mercadopago.com.ar/developers/pt/docs/split-payments-1-n/resources/common-errors.md

\# 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. > NOTE > > 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": \[\] } \`\`\`