Skip to main content
The YuvexPay API uses standard HTTP status codes and returns structured error responses.

Error response format

All errors follow a consistent structure:
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": {
      "amount": "Must be greater than 0.01"
    }
  }
}
FieldTypeDescription
error.codestringMachine-readable error code.
error.messagestringHuman-readable description.
error.detailsobjectAdditional context (optional).

HTTP status codes

StatusMeaning
200Success.
201Resource created.
400Bad request (validation error, missing fields).
401Unauthorized (missing, invalid or revoked API key).
403Forbidden (insufficient permissions).
404Resource not found.
409Conflict (idempotency key mismatch).
429Rate limit exceeded.
500Internal server error.
503Service unavailable.

Error codes

Authentication errors

CodeStatusDescription
API_KEY_REQUIRED401No Authorization: Bearer header supplied.
INVALID_API_KEY401The key is unknown, revoked, expired, or its environment does not match the request.
FORBIDDEN403The key is valid but lacks the required scope, or the request came from an IP outside the key’s allowlist.
IP_NOT_ALLOWED403The request came from an IP address outside the key’s IP allowlist.

Validation errors

CodeStatusDescription
VALIDATION_ERROR400Request body or query parameters failed validation. Check details for specifics.

Idempotency errors

CodeStatusDescription
IDEMPOTENCY_KEY_REQUIRED400POST endpoints that require an X-Idempotency-Key header.
IDEMPOTENCY_PAYLOAD_MISMATCH409The same idempotency key was used with a different request body.
IDEMPOTENCY_CONFLICT409The request is still being processed from a previous attempt.

Rate limiting errors

CodeStatusDescription
RATE_LIMIT_EXCEEDED429Too many requests. Check response headers for reset timing.

Resource errors

CodeStatusDescription
NOT_FOUND404The requested resource does not exist or does not belong to your account.

Payment errors

CodeStatusDescription
PAYMENT_CREATION_BLOCKED403The account is currently not allowed to create payments (KYB pending, suspended, or the requested method is disabled).
AMOUNT_REQUIRED400A direct amount is required when no productId is supplied.
CUSTOMER_DATA_REQUIRED400The selected payment method requires customer data and none was provided.
CARD_HOLDER_INFO_REQUIRED400Direct card payments require card.holderInfo (postal code and address number).
CARD_REMOTE_IP_REQUIRED400Direct card payments require card.remoteIp (the payer’s IP address).
INSTALLMENTS_NOT_SUPPORTED400Card installments are not currently supported; send installments: 1 or omit.
PROVIDER_TEMPORARILY_UNAVAILABLE502A downstream payment processor is unavailable. Retry with backoff.

Refund errors

CodeStatusDescription
INVALID_STATUS400The payment is not in a refundable status.
PARTIAL_REFUND_NOT_SUPPORTED400Only full refunds are currently supported. Send no amount or send the full remaining refundable amount.
ALREADY_REFUNDED400The payment has already been fully refunded.
REFUND_IN_PROGRESS409A refund is already being processed for this payment.
REFUND_NOT_SUPPORTED400Refunds are not supported for this payment method or processing route.
INSUFFICIENT_BALANCE_FOR_REFUND400Your available balance is not sufficient to issue this refund.

Withdrawal errors

CodeStatusDescription
WITHDRAWAL_BELOW_MINIMUM400The amount is below the minimum withdrawal value.
INSUFFICIENT_BALANCE400Your available balance is not sufficient.
WITHDRAWAL_LIMIT_EXCEEDED400The amount exceeds the remaining daily or nightly limit.
WITHDRAWALS_BLOCKED403Withdrawals are currently disabled for the account.
INVALID_PIX_KEY400The destination PIX key is not a recognizable CPF, CNPJ, e-mail, phone, or random key.
INVALID_WITHDRAWAL_RECIPIENT403The PIX key does not belong to a permitted recipient (for CNPJ accounts, the key must match the company name or registered partners).
PIX_KEY_VALIDATION_FAILED400The PIX key could not be validated.
CREDITOR_DOCUMENT_UNAVAILABLE403Your account’s CNPJ (business) or owner CPF (individual) is not on file. Complete KYB/KYC before withdrawing.
VERIFICATION_REQUIRED403Account verification is required before withdrawals can be processed.

Server errors

CodeStatusDescription
INTERNAL_ERROR500Unexpected server error. Retry with exponential backoff.
SERVICE_UNAVAILABLE503The service is temporarily unavailable. Retry after a short delay.

Handling errors

async function createPayment(data) {
  const response = await fetch("https://api.yuvexpay.com/v1/payments", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.YUVEX_API_KEY}`,
      "Content-Type": "application/json",
      "X-Idempotency-Key": generateIdempotencyKey(),
    },
    body: JSON.stringify(data),
  });

  if (!response.ok) {
    const { error } = await response.json();

    switch (response.status) {
      case 400:
        console.error("Validation error:", error.details);
        break;
      case 401:
      case 403:
        throw new Error(`Auth failed: ${error.code}${error.message}`);
      case 409:
        console.warn("Duplicate request detected");
        break;
      case 429:
        const retryAfter = response.headers.get("X-RateLimit-Reset");
        await sleep(retryAfter * 1000);
        return createPayment(data);
      default:
        throw new Error(`API error: ${error.message}`);
    }
  }

  return response.json();
}