When the Yuno API returns an error, the response body always follows this structure:
{
"code": "INVALID_PARAMETERS",
"messages": [
"customer.document.document_number is required for PIX payments"
]
}
code field identifies the specific error class. The messages array provides one or more human-readable descriptions that detail which field or condition triggered the error. Always log both fields — the messages content is often sufficient to identify the fix without further research.
The messages array may contain multiple entries when a single request violates more than one validation rule simultaneously. Fix all reported issues before retrying.
400 Bad Request
400 errors indicate that the request was syntactically or semantically invalid. The request reached Yuno’s servers but was rejected before processing.
| Code | Description | Recommended Fix |
|---|
INVALID_REQUEST | The request body is malformed or cannot be parsed. | Validate that the request body is valid JSON. Check for trailing commas, unescaped characters, or encoding issues. |
INVALID_PARAMETERS | One or more fields contain invalid values or incorrect formats. | Review the messages array for the specific field. Verify types, formats (e.g., ISO 4217 currency, UUID), and allowed enum values. |
MISSING_PARAMETERS | One or more required fields are absent from the request body. | Add the missing fields identified in messages. Consult the endpoint schema in the API reference. |
INVALID_STATUS | The requested operation is not allowed for the payment’s current status. | Check the payment’s current status field before issuing the action. For example, you cannot capture a payment that is already SUCCEEDED or CANCELLED. |
COUNTRY_NOT_SUPPORTED | The specified country is not supported for this payment method or account. | Verify that the country field uses a valid ISO 3166-1 alpha-2 code and that the payment method is enabled for that country in the Yuno Dashboard. |
CURRENCY_NOT_ALLOWED | The specified currency is not allowed for this account or payment method. | Confirm the currency uses ISO 4217 format and is enabled for your merchant account. Some payment methods enforce a specific currency (e.g., PIX requires BRL). |
CUSTOMER_ID_DUPLICATED | A customer with the provided external ID already exists. | Use the existing customer ID or provide a unique customer_external_id value. |
INVALID_AMOUNT | The payment amount is zero, negative, or formatted incorrectly. | Ensure amount.value is a positive number. Verify the number of decimal places matches the currency’s convention (e.g., 100.00 for BRL, not 10000). |
INVALID_ACCOUNT_ID | The account-code header references an account that does not exist or is not accessible. | Verify the account-code header value in the Yuno Dashboard under Settings > API Keys. |
INVALID_TRANSACTION | The transaction referenced in the request is invalid or cannot be found. | Confirm the transaction ID is correct and belongs to a payment in the current account. |
CHECKOUT_SESSION_NOT_FOUND | The checkout session does not exist or has expired. | Checkout sessions expire after 60 minutes. Create a new session via POST /v1/checkout-sessions and re-initialize the SDK with the new token. |
PAYMENT_NOT_FOUND | No payment exists with the provided payment ID. | Verify the payment ID. Confirm the request is using the correct environment (sandbox vs. production) and the correct account-code. |
CUSTOMER_NOT_FOUND | No customer exists with the provided customer ID or external ID. | Confirm the customer was created in the same environment and account. Customer records are not shared between sandbox and production. |
IDEMPOTENCY_DUPLICATED | The X-Idempotency-Key header value has already been used for a different request payload. | Generate a new unique idempotency key (UUID v4 recommended) for each distinct payment attempt. Do not reuse keys across different requests. |
PAYMENT_METHOD_NOT_FOUND | The specified payment method is not available or not enabled. | Verify the payment method is enabled for your account and country in the Yuno Dashboard under Settings > Payment Methods. |
SUBSCRIPTION_NOT_FOUND | No subscription exists with the provided subscription ID. | Verify the subscription ID and confirm it was created in the same environment and account. |
401 Unauthorized
401 errors indicate an authentication failure. The request did not include valid credentials or the credentials provided have expired or been invalidated.
| Code | Description | Recommended Fix |
|---|
INVALID_CREDENTIALS | The public-api-key or private-secret-key header value is incorrect. | Copy the credentials directly from Dashboard > Settings > API Keys. Ensure you are using sandbox keys for https://api-sandbox.y.uno/v1 and production keys for the production base URL. |
EXPIRED_CREDENTIALS | The credentials have expired or been rotated. | Regenerate API keys in Dashboard > Settings > API Keys and update all services using the old credentials. |
UNKNOWN_IP_ADDRESS | The request originated from an IP address not on the allowlist for your account. | Add the server’s egress IP to the allowlist in Dashboard > Settings > Security, or remove the IP restriction if not required. |
INVALID_TOKEN | The checkout session token or one-time token provided is malformed or has been tampered with. | Re-create the checkout session or re-fetch the one-time token. Ensure tokens are passed verbatim without modification. |
TOKEN_IN_USE | The token has already been used for a transaction and cannot be reused. | Tokens are single-use. Generate a new checkout session or one-time token for each payment attempt. |
403 Forbidden
403 errors indicate the request was authenticated but the caller lacks permission to perform the action.
| Code | Description | Recommended Fix |
|---|
AUTHORIZATION_REQUIRED | The caller does not have permission to access this resource. Commonly caused by a missing or incorrect account-code header, or by using a public key for a private endpoint. | Verify the account-code header is present and correct. Confirm you are using private-secret-key for server-side endpoints. The public-api-key is for client-side SDK initialization only — never for direct API calls that create or modify payments. |
405 Method Not Allowed
| Code | Description | Recommended Fix |
|---|
UNSUPPORTED_METHOD | The HTTP method used is not supported for this endpoint. | Verify the HTTP method (GET, POST, PUT, PATCH, DELETE) against the API reference. For example, payment creation requires POST /v1/payments, not GET. |
500 and 504 Server Errors
Server errors indicate a problem on Yuno’s side or a downstream timeout. These are generally transient.
| Code | HTTP Status | Description | Recommended Fix |
|---|
INTERNAL_ERROR | 500 | An unexpected error occurred on Yuno’s servers. | Retry with exponential backoff. If the error persists across multiple retries, escalate to Yuno support with the full request, response, and timestamp. |
REQUEST_TIMEOUT | 504 | The request timed out before Yuno received a response from a downstream provider. | Implement a retry with exponential backoff. Check Yuno’s status page for active provider incidents before retrying aggressively. |
For INTERNAL_ERROR and REQUEST_TIMEOUT, always use idempotency keys (X-Idempotency-Key) when retrying. Without an idempotency key, a retry may create a duplicate payment if the original request succeeded on the server before the timeout.
