Errores y códigos de respuesta

Cómo comunica errores la API de Toku.

Toku entrega dos niveles de información según dónde ocurre el problema: el rechazo de la petición (envelope de error de la API) y, en cobros, el resultado del medio de pago (código de gateway con gravedad).

Estructura de un error de la API

Cuando la API rechaza una petición, responde con un cuerpo canónico y el detalle anidado bajo error:

{
  "error": {
    "message": "Descripción legible de qué salió mal.",
    "code": "TKxxxxx"
  }
}

• El status HTTP indica la clase del problema — cada código y su significado, en Códigos HTTP de respuesta.
• error.message — descripción legible del error.
• error.code — código interno de Toku, estable, con formato TKxxxxx. El listado completo, con la estructura del código y el significado de cada uno, vive en Códigos de API.

Detalle de validación (422)

Algunos endpoints acompañan el 422 con un arreglo detail en la raíz del cuerpo — junto al envelope, no dentro de él — que desglosa campo a campo lo que no validó:

{
  "detail": [
    {
      "loc": ["body", "amount"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Cada entrada indica dónde está el problema (loc), qué ocurrió (msg) y qué validación falló (type).

No todos los endpoints entregan ese desglose: el resto responde el 422 sólo con el envelope, donde error.code identifica la validación que falló. Revisa la página del endpoint, en la categoría Recursos, para saber qué cuerpo devuelve.

Códigos de respuesta HTTP

Las respuestas usan la convención de códigos de estado HTTP para indicar si la llamada fue exitosa o falló. El significado de cada uno vive en Códigos HTTP de respuesta.

Códigos de cobro y medios de pago

Los cobros y medios de pago incluyen además un código de resultado (toku_response_code) con una gravedad que indica cómo tratarlo:

El detalle completo — cada código con su gravedad y sus mensajes al cliente y al customer — vive en Códigos de pago rechazado, generado desde una fuente única.