Skip to main content
This section covers the most common issues encountered when integrating with Yuno, from authentication errors and API schema violations to provider declines and SDK configuration problems. Each guide is written for engineers who need a fast, precise answer without reading the full API reference. If you haven’t already, enable verbose logging in your SDK initialization and capture full request/response pairs before debugging — most issues are resolved once the complete error object is visible.

​
What’s in this section

Error Code Reference

Every Yuno API error code — 400, 401, 403, 500, and 504 — with descriptions and recommended fixes.

Common Integration Issues

Step-by-step fixes for the most frequent problems: credential mismatches, expired sessions, CORS errors, PIX document validation, and more.

Provider Errors

How to interpret downstream provider decline codes, map them to user-facing messages, and decide when to retry.

FAQ

Direct answers to common questions about sandbox vs. production, idempotency, payment statuses, subscriptions, and more.

​
Before you escalate

Work through these steps before opening a support ticket — they resolve the majority of integration issues.
1

Capture the full error response

Log the complete response body, not just the HTTP status code. Yuno error responses include code and messages fields that identify the exact problem.
2

Confirm your environment

Sandbox and production use different credentials and have different payment method availability. Verify you are using the correct API keys for the environment you are testing in.
3

Check the error code reference

Look up the error code value in the Error Code Reference. Most 400 and 401 errors have a deterministic fix.
4

Review the common issues guide

The Common Integration Issues guide covers the eight most frequent failure patterns with code-level fixes.
5

Check provider errors separately

If the payment reaches a provider but is declined, the issue is in payment.transaction.provider_code, not the Yuno API response. See Provider Errors.

​
How to get help

If the guides in this section do not resolve your issue, escalate to Yuno support with the following information to get the fastest resolution:
  • Environment: Sandbox or Production
  • Merchant / Account ID: Anonymize or redact before sharing
  • Timestamp: ISO 8601 format (e.g., 2026-01-31T14:32:00Z)
  • Full API request: Method, endpoint, headers (redact private-secret-key), and body
  • Full API response: Status code and complete response body
  • SDK version: If using @yuno-payments/sdk-web or a mobile SDK, include the version
  • Steps already attempted: List what you have tried so support can skip to the next step
Never include raw API keys or private-secret-key values in support tickets or public forums. Redact credentials before sharing any logs.