Errores

Si algo falla, success es false y error describe el código, el mensaje y, si aplica, el detalle por campo.

Campo	Qué es
success	Siempre false en errores
message	Mensaje legible (igual que error.message)
error.code	Código de dominio (p. ej. MERCHANT_NOT_FOUND)
error.message	Qué falló
error.request_id	Id de la petición para soporte
error.doc_url	Enlace a la documentación del error
error.details	Lista opcional de { field, code, message }

Códigos HTTP

HTTP	Cuándo
400	Petición malformada
401	Falta Authorization o la key no es válida
403	Sin permiso, o KYB_REQUIRED (falta sello KUTI habilitado para live)
404	El negocio u otro recurso no existe
409	Conflicto (duplicado o Idempotency-Key reutilizada con otro payload)
422	Validación de dominio o body inválido

403 — producción sin verificaciónjson

{
  "success": false,
  "message": "Completa la verificación KUTI para operar en modo producción.",
  "error": {
    "code": "KYB_REQUIRED",
    "message": "Completa la verificación KUTI para operar en modo producción.",
    "request_id": "req_01J8Z3K4M5N6P7Q8R9S0T1U2V3"
  }
}

404json

{
  "success": false,
  "message": "The requested merchant does not exist.",
  "error": {
    "code": "MERCHANT_NOT_FOUND",
    "message": "The requested merchant does not exist.",
    "request_id": "req_01J8Z3K4M5N6P7Q8R9S0T1U2V3",
    "doc_url": "https://docs.kuti.pe/errors/MERCHANT_NOT_FOUND"
  }
}

401json

{
  "success": false,
  "message": "Missing or invalid credentials.",
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid credentials.",
    "request_id": "req_01J8Z3K4M5N6P7Q8R9S0T1U2V3"
  }
}

422json

{
  "success": false,
  "message": "Validation failed.",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed.",
    "request_id": "req_01J8Z3K4M5N6P7Q8R9S0T1U2V3",
    "details": [
      {
        "field": "tax_id.value",
        "code": "INVALID_FORMAT",
        "message": "RUC must match the expected pattern."
      }
    ]
  }
}