Códigos de error

Todo error de la API devuelve el mismo sobre:

{
  "error": {
    "code": "payment_rejected",
    "message": "The selected currency is invalid.",
    "documentation_url": "https://app.so-amtar.com/docs/errors#payment_rejected"
  }
}

Código HTTP	Significado
400	Solicitud mal formada (cabecera no válida, JSON no válido)
401	Autenticación (clave ausente, no válida o revocada)
403	Autorización (permiso insuficiente)
404	Recurso no encontrado para este comercio
409	Conflicto (idempotencia incoherente, solicitud en curso)
422	Validación de negocio (límite superado, estado incoherente)
429	Límite de solicitudes
500	Error interno (avise al soporte)
502	Orange Money no disponible

Lista completa

Autenticación

• missing_credentials — cabecera Authorization ausente
• invalid_api_key — clave desconocida, revocada o caducada, o IP fuera de la lista autorizada
• scope_insufficient — la clave no tiene el permiso que exige esta ruta

Idempotencia

• idempotency_key_too_long — más de 255 caracteres
• idempotency_conflict — misma clave con un cuerpo distinto, O solicitud todavía en curso

Pagos

• payment_rejected — validación de negocio (proveedor, divisa, precisión del importe, límite, KYC)
• gateway_error — Orange Money rechazó iniciar el pago (502)
• transaction_not_found — id o referencia desconocidos para este comercio (o creados en el otro modo)

Reembolsos (POST/v1/refunds, scope can_refund)

• transaction_not_found (404) — transacción desconocida para este comercio
• refunds_disabled (422) — los reembolsos no están activados para su cuenta
• refund_environment_mismatch (422) — clave de prueba sobre una transacción live o al revés
• transaction_not_refundable (422) — el estado de la transacción no es success
• non_payment_transaction_refund (422) — solo se reembolsan pagos (no pagos salientes)
• provider_refund_unsupported (422) — el proveedor no admite reembolsos
• refund_payer_phone_missing (422) — el pago no tiene número del pagador al que abonar
• amount_must_be_positive (422) — amount debe ser mayor que cero
• transaction_already_fully_refunded (422) — el pago ya está totalmente reembolsado
• refund_exceeds_refundable (422) — amount supera el importe restante reembolsable
• refund_rejected (422) — reembolso rechazado por otro motivo de negocio
• scope_insufficient (403) — la clave no tiene el scope can_refund
• refund_not_found (404) — GET/v1/refunds/{id}: id o referencia desconocidos

Pagos salientes (payouts)

• payout_not_allowed_in_test_mode — los pagos salientes requieren una clave live (sk_live_…)

Pagos divididos (splits)

• split_rejected — total superior al importe de la transacción, beneficiario inactivo o transacción ya finalizada

Qué hacer

Código	Acción recomendada
4xx (validación)	Corregir la solicitud y usar una nueva Idempotency-Key
401	Verificar la clave. No reintentar.
409	Revisar su lógica de idempotencia
429	Esperar el Retry-After y reintentar
5xx	Reintentar con la misma Idempotency-Key, con espera exponencial
502	Orange Money no disponible: reintentar tras unos segundos

Notificar un error

Escriba a support@so-amtar.com indicando:

• el código de error
• el documentation_url
• la fecha y hora exactas (UTC)
• su merchant_ref o el id SOAMTAR
• la cabecera X-Request-Id de la respuesta (si existe)