Ir al contenido

Errores

Al terminar esta página sabrás la forma de un error, qué código HTTP y de negocio esperar en cada situación, y qué acción tomar en cada caso.

422 Unprocessable Entity
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid return identifier.",
"field": "return_id",
"request_id": "req_4f9c2b7e1a8d4c3b9e6f0a1d2c3b4e5f"
}
}
Campo Presente Descripción
code Siempre Código estable. Decide tu lógica sobre este campo, nunca sobre message.
message Siempre Texto en inglés para depuración humana. No lo muestres al pagador ni lo traduzcas para decidir un flujo.
field Cuando aplica El campo del cuerpo o la cabecera que causó el error.
request_id Siempre Identificador único de la request (req_ y 32 caracteres hexadecimales). Compártelo con Neat al pedir ayuda: con él encontramos tu request en nuestros registros. Nunca compartas tu API key, tu webhook_secret ni datos de tarjeta.
HTTP Código Cuándo Qué hacer
401 UNAUTHORIZED Falta el encabezado Authorization, no usa el prefijo Bearer o el token viene vacío. Corrige el encabezado, ver Si recibes un 401.
401 INVALID_API_KEY La API key no existe o fue revocada. Revisa que mandas la API key y no el webhook_secret; si sigue, confirma la credencial vigente con Neat.
403 PROVIDER_DISABLED Tu comercio está deshabilitado. Contacta a Neat.
422 VALIDATION_ERROR Un campo no cumple su formato, incluido un monto fuera de tus límites, o Idempotency-Key ausente o inválida. Corrige el campo indicado en field.
422 RETURN_NOT_REGISTERED El return_id no está registrado o no está activo. Usa un return_id vigente, ver Alta de tu comercio.
409 IDEMPOTENCY_CONFLICT Repetiste Idempotency-Key con un cuerpo distinto. Usa el cuerpo original, o una llave nueva si de verdad es otra solicitud.
422 BENEFICIARY_REQUIRED Tu comercio cobra por varios beneficiarios y la sesión no trae beneficiary. Manda el beneficiario de ese cobro, ver Sesiones de checkout.
422 BENEFICIARY_NOT_ALLOWED La sesión trae beneficiary y tu comercio cobra a la cuenta acordada con Neat. Quita el campo, o pide a Neat habilitar el cobro por beneficiario.
422 CATEGORY_NOT_ALLOWED La sesión trae una category que tu comercio no tiene habilitada. Usa una de las categorías acordadas con Neat, o pide habilitar la nueva.
422 FEE_BEARER_NOT_ALLOWED La sesión trae un fee_bearer que tu comercio no tiene habilitado. Omite el campo o usa la forma acordada con Neat, ver Quién paga la comisión.
422 AMOUNT_BELOW_FEE Tu comercio absorbe la comisión y el monto no deja nada que depositar con alguna de tus tasas. Sube el monto; con las tasas de tarjeta solo pasa con montos de unos pocos centavos.
409 OBLIGATION_CONFLICT El external_reference ya existe con otro monto, moneda, categoría, concepto o beneficiario, aunque no se haya pagado. Manda los mismos términos. Si la cuota cambió de verdad, usa una referencia nueva con versión, ver Sesiones de checkout.
409 OBLIGATION_ALREADY_PAID Esa obligación ya tiene un pago confirmado. Consulta el pago; no inicies otro cobro.
409 PAYMENT_IN_PROGRESS Esa obligación tiene un cobro en curso. Consulta el estado antes de reintentar.
429 RATE_LIMITED Superaste 120 solicitudes por minuto con esa credencial. Respeta Retry-After.
HTTP Código Cuándo Qué hacer
401 UNAUTHORIZED / INVALID_API_KEY Igual que arriba. Igual que arriba.
403 PROVIDER_DISABLED Igual que arriba. Igual que arriba.
404 RESOURCE_NOT_FOUND El sessionId no existe, o pertenece a otro comercio. Verifica el identificador; la API no distingue ambos casos entre sí.
429 RATE_LIMITED Superaste 300 solicitudes por minuto con esa credencial. Respeta Retry-After.
HTTP Código Cuándo Qué hacer
401 UNAUTHORIZED / INVALID_API_KEY Igual que arriba. Igual que arriba.
403 PROVIDER_DISABLED Igual que arriba. Igual que arriba.
429 RATE_LIMITED Superaste 10 solicitudes por minuto con esa credencial. Respeta Retry-After.
HTTP Código Cuándo
400 INVALID_JSON El cuerpo viene vacío o no es JSON válido.
400 BAD_REQUEST El request no se pudo aceptar como vino; el caso típico es un cuerpo que no coincide con su Content-Length.
400 INVALID_PATH El path no es una URL válida.
414 INVALID_PATH Un parámetro del path excede el largo permitido.
404 ROUTE_NOT_FOUND La ruta no existe. Revisa el método y el path.
413 PAYLOAD_TOO_LARGE El cuerpo supera 16 KiB.
415 UNSUPPORTED_MEDIA_TYPE Falta Content-Type: application/json o el cuerpo viene con otro tipo.
500 INTERNAL_ERROR Cualquier falla no clasificada del lado de Neat.

Todos menos el último son errores de tu lado: corrige el request antes de reintentar, sin reintento automático. 429 RATE_LIMITED sí se reintenta, esperando lo que diga Retry-After, y 500 INTERNAL_ERROR también, con espera creciente.

Estos códigos aparecían en un borrador anterior del contrato de integración y no existen en v1: IDEMPOTENCY_IN_PROGRESS, INSUFFICIENT_SCOPE. Si tu integración ya los maneja por haber seguido ese borrador, puedes dejar el manejo; hoy no los vas a recibir.