Skip to main content
Las respuestas de error de Connect usan un envelope consistente: 
{
  "error": {
    "type": "invalid_request_error",
    "code": "idempotency_key_required",
    "message": "Idempotency-Key header is required for this endpoint.",
    "param": null,
    "doc_url": "https://docs.zopay.cash/errors/idempotency_key_required"
  }
}

​
Campos

CampoDescripción
typeCategoría (por ejemplo authentication_error, invalid_request_error, not_found_error).
codeCódigo legible por máquina.
messageMensaje para humanos.
paramCampo de entrada relacionado, si aplica.
doc_urlURL base https://docs.zopay.cash/errors/ + code.

​
Códigos frecuentes

CódigoHTTP típicoCuándo
authentication_required401Sin header, clave inválida o malformada.
expired_credential401Clave con expires_at en el pasado. Rota desde el panel. Ver Autenticación.
account_pending_approval403Cuenta Connect no aprobada en endpoints que mueven fondos.
forbidden_scope403La clave no tiene el scope requerido por el endpoint. Mintea una nueva o extiende los scopes.
not_yet_available501Endpoint registrado pero sin implementación aún.
idempotency_key_required400Falta Idempotency-Key en rutas que lo exigen.
idempotency_conflict409Misma Idempotency-Key con body distinto.
(validación de body)422Body estructuralmente inválido (campo faltante, tipo equivocado). error.param nombra la llave. Ver 422 vs 400.
catalog_invalid400Asset desconocido. Verifica con GET /capabilities.
min_usdt_amount_requires_solana400USDT en red no-Solana con amount <= 5.5. Ver Reglas de selección de red.
event_not_found404evt_… no existe en tu tenant. Misma forma de envelope que un id cross-tenant — los eventos no son enumerables entre orgs.
webhook_endpoint_not_configured400Llamaste a POST /events/:id/replay pero no tienes un webhook habilitado. Configúralo y reintenta.
Errores de autenticación detallados en Autenticación. Idempotencia en Idempotencia. Eventos en Events.