Errores

Todo error de la API sale en el mismo formato y con un código estable. Tu código decide por el código, nunca por el texto.

El formato

Los errores van con Content-Type: application/problem+json (RFC 9457):

HTTP/1.1 400 Bad Request

{
  "type": "https://kicket.club/desarrolladores/errores#invalid_request",
  "title": "Pedido inválido",
  "status": 400,
  "detail": "`limit` tiene que ser un entero entre 1 y 500.",
  "code": "invalid_request",
  "request_id": "req_3f9a1c7e2b8d4a6f0c5e1b72",
  "errors": [
    {
      "field": "limit",
      "message": "`limit` tiene que ser un entero entre 1 y 500."
    }
  ]
}

Campo	Qué es
`code`	El código estable (la lista de abajo). Es lo que tiene que mirar tu código.
`type`	La URL de la explicación de ese código, en esta página.
`title`	El nombre del código, para una persona.
`status`	El mismo status HTTP de la respuesta.
`detail`	Qué pasó y qué hacer, para quien lee el log. Puede cambiar: no lo compares.
`request_id`	El id del pedido (también en el header X-Request-Id). Mandánoslo si nos escribís.
`errors`	Cuando falla un parámetro o el cuerpo: qué campo y por qué. Puede no estar.

Algunos errores traen además un header útil: WWW-Authenticate en el 401 y el 403 de permisos, Retry-After en el 429, Allow en el 405. El 410 trae deleted_at en el cuerpo.

Los códigos

`invalid_request`HTTP 400

Qué significa: Un parámetro o el cuerpo no tiene la forma esperada: una fecha sin huso, un limit fuera de rango, un valor que no está en la lista o un parámetro que la ruta no conoce.
Qué hacer: Corregí el pedido. errors[] dice qué campo falló y por qué. Nunca se ignora un valor que no se entiende.
¿Reintentar?: No: corregí el pedido.

`invalid_cursor`HTTP 400

Qué significa: El cursor está roto, es de otro listado o cambiaron los filtros entre una página y la siguiente.
Qué hacer: Pasá el next_cursor tal cual lo recibiste y con los mismos filtros. Si cambiás un filtro, empezá sin cursor.
¿Reintentar?: No: corregí el pedido.

`unauthorized`HTTP 401

Qué significa: Falta el token, venció, es de una credencial revocada o es de antes de rotar el secreto.
Qué hacer: Pedí un token nuevo en POST /oauth/token y repetí el pedido una sola vez. Si vuelve a fallar, revisá la credencial.
¿Reintentar?: Sí, después de esperar.

`insufficient_scope`HTTP 403

Qué significa: El token no tiene el permiso que pide la ruta. El header WWW-Authenticate dice cuál falta.
Qué hacer: Pedile al dueño de la cuenta una credencial con ese permiso (o pedí el token sin acotar scope).
¿Reintentar?: No: corregí el pedido.

`forbidden`HTTP 403

Qué significa: La cuenta no tiene la API habilitada, dejó de ser la cuenta principal de su cadena, o pediste una sucursal (branch_id) que no es de la cuenta.
Qué hacer: Revisá el branch_id. Si es la cuenta, el dueño se la tiene que pedir a Kicket.
¿Reintentar?: No: corregí el pedido.

`not_found`HTTP 404

Qué significa: El objeto no existe o no es de esta cuenta (no se distingue un caso del otro).
Qué hacer: Revisá el id. Si lo sacaste de un listado, puede haberse borrado: mirá las lápidas con updated_since.
¿Reintentar?: No: corregí el pedido.

`method_not_allowed`HTTP 405

Qué significa: La ruta existe pero no acepta ese método. El header Allow dice cuáles sí.
Qué hacer: Usá uno de los métodos de Allow.
¿Reintentar?: No: corregí el pedido.

`conflict`HTTP 409

Qué significa: Otro producto o combo de la misma sucursal ya usa ese código externo (sin distinguir mayúsculas).
Qué hacer: Sacale el código al otro producto, o elegí otro código.
¿Reintentar?: No: corregí el pedido.

`gone`HTTP 410

Qué significa: El objeto existió y se borró. El cuerpo trae deleted_at.
Qué hacer: Borralo de tu sistema. En la sincronización incremental aparece como lápida (deleted: true).
¿Reintentar?: No: corregí el pedido.

`unsupported_media_type`HTTP 415

Qué significa: El cuerpo no viene en el formato que acepta la ruta.
Qué hacer: Mandá Content-Type: application/json en el PATCH.
¿Reintentar?: No: corregí el pedido.

`rate_limited`HTTP 429

Qué significa: Pasaste los 300 pedidos por minuto de la credencial, los 600 de la cuenta (sumando todas sus credenciales) o los 60 pedidos pesados de la cuenta (el reporte diario y los listados filtrados por estado, canal, medio o fecha del cobro).
Qué hacer: Esperá los segundos que dice Retry-After y reintentá. Bajá el ritmo: no mandes más pedidos en paralelo.
¿Reintentar?: Sí, después de esperar.

`internal_error`HTTP 500

Qué significa: Algo falló de nuestro lado.
Qué hacer: Reintentá con espera creciente. Si se repite, escribinos con el request_id.
¿Reintentar?: Sí, después de esperar.

`service_unavailable`HTTP 503

Qué significa: La API no está disponible en este momento.
Qué hacer: Reintentá con espera creciente. No es un problema de tu credencial.
¿Reintentar?: Sí, después de esperar.

POST /oauth/token contesta sus errores con el formato de OAuth 2.0 (RFC 6749 §5.2): { "error": "…", "error_description": "…" }. El límite (429) y la API no disponible (503) van como problem+json, igual que el resto.

error	HTTP	Cuándo
`invalid_request`	400	Falta `grant_type`, un parámetro vino dos veces, la credencial vino por Basic y en el cuerpo, o el cuerpo no es un formulario ni JSON.
`invalid_client`	401	La credencial no existe, el secreto no coincide o fue revocada. Trae `WWW-Authenticate: Basic`.
`unsupported_grant_type`	400	El `grant_type` no es `client_credentials`.
`invalid_scope`	400	Pediste un permiso que la credencial no tiene (o la credencial no tiene ninguno).
`unauthorized_client`	400	La cuenta no tiene la API habilitada.

Cómo manejarlos

4xx (salvo 401 y 429): el pedido está mal. Reintentarlo igual da lo mismo. Logueá code, detail y request_id.
401: pedí un token nuevo y repetí una sola vez.
429: esperá Retry-After segundos. Ver Límites de uso.
5xx: reintentá con espera creciente (2, 4, 8… segundos) y un tope de intentos. Todas las rutas de lectura se pueden repetir sin riesgo; el PATCH también (deja el mismo código).

El formato

Los errores van con Content-Type: application/problem+json (RFC 9457):

HTTP/1.1 400 Bad Request

{
  "type": "https://kicket.club/desarrolladores/errores#invalid_request",
  "title": "Pedido inválido",
  "status": 400,
  "detail": "`limit` tiene que ser un entero entre 1 y 500.",
  "code": "invalid_request",
  "request_id": "req_3f9a1c7e2b8d4a6f0c5e1b72",
  "errors": [
    {
      "field": "limit",
      "message": "`limit` tiene que ser un entero entre 1 y 500."
    }
  ]
}

Campo	Qué es
`code`	El código estable (la lista de abajo). Es lo que tiene que mirar tu código.
`type`	La URL de la explicación de ese código, en esta página.
`title`	El nombre del código, para una persona.
`status`	El mismo status HTTP de la respuesta.
`detail`	Qué pasó y qué hacer, para quien lee el log. Puede cambiar: no lo compares.
`request_id`	El id del pedido (también en el header X-Request-Id). Mandánoslo si nos escribís.
`errors`	Cuando falla un parámetro o el cuerpo: qué campo y por qué. Puede no estar.

Algunos errores traen además un header útil: WWW-Authenticate en el 401 y el 403 de permisos, Retry-After en el 429, Allow en el 405. El 410 trae deleted_at en el cuerpo.

Los códigos

`invalid_request`HTTP 400

Qué significa: Un parámetro o el cuerpo no tiene la forma esperada: una fecha sin huso, un limit fuera de rango, un valor que no está en la lista o un parámetro que la ruta no conoce.
Qué hacer: Corregí el pedido. errors[] dice qué campo falló y por qué. Nunca se ignora un valor que no se entiende.
¿Reintentar?: No: corregí el pedido.

`invalid_cursor`HTTP 400

Qué significa: El cursor está roto, es de otro listado o cambiaron los filtros entre una página y la siguiente.
Qué hacer: Pasá el next_cursor tal cual lo recibiste y con los mismos filtros. Si cambiás un filtro, empezá sin cursor.
¿Reintentar?: No: corregí el pedido.

`unauthorized`HTTP 401

Qué significa: Falta el token, venció, es de una credencial revocada o es de antes de rotar el secreto.
Qué hacer: Pedí un token nuevo en POST /oauth/token y repetí el pedido una sola vez. Si vuelve a fallar, revisá la credencial.
¿Reintentar?: Sí, después de esperar.

`insufficient_scope`HTTP 403

Qué significa: El token no tiene el permiso que pide la ruta. El header WWW-Authenticate dice cuál falta.
Qué hacer: Pedile al dueño de la cuenta una credencial con ese permiso (o pedí el token sin acotar scope).
¿Reintentar?: No: corregí el pedido.

`forbidden`HTTP 403

Qué significa: La cuenta no tiene la API habilitada, dejó de ser la cuenta principal de su cadena, o pediste una sucursal (branch_id) que no es de la cuenta.
Qué hacer: Revisá el branch_id. Si es la cuenta, el dueño se la tiene que pedir a Kicket.
¿Reintentar?: No: corregí el pedido.

`not_found`HTTP 404

Qué significa: El objeto no existe o no es de esta cuenta (no se distingue un caso del otro).
Qué hacer: Revisá el id. Si lo sacaste de un listado, puede haberse borrado: mirá las lápidas con updated_since.
¿Reintentar?: No: corregí el pedido.

`method_not_allowed`HTTP 405

Qué significa: La ruta existe pero no acepta ese método. El header Allow dice cuáles sí.
Qué hacer: Usá uno de los métodos de Allow.
¿Reintentar?: No: corregí el pedido.

`conflict`HTTP 409

Qué significa: Otro producto o combo de la misma sucursal ya usa ese código externo (sin distinguir mayúsculas).
Qué hacer: Sacale el código al otro producto, o elegí otro código.
¿Reintentar?: No: corregí el pedido.

`gone`HTTP 410

Qué significa: El objeto existió y se borró. El cuerpo trae deleted_at.
Qué hacer: Borralo de tu sistema. En la sincronización incremental aparece como lápida (deleted: true).
¿Reintentar?: No: corregí el pedido.

`unsupported_media_type`HTTP 415

Qué significa: El cuerpo no viene en el formato que acepta la ruta.
Qué hacer: Mandá Content-Type: application/json en el PATCH.
¿Reintentar?: No: corregí el pedido.

`rate_limited`HTTP 429

Qué significa: Pasaste los 300 pedidos por minuto de la credencial, los 600 de la cuenta (sumando todas sus credenciales) o los 60 pedidos pesados de la cuenta (el reporte diario y los listados filtrados por estado, canal, medio o fecha del cobro).
Qué hacer: Esperá los segundos que dice Retry-After y reintentá. Bajá el ritmo: no mandes más pedidos en paralelo.
¿Reintentar?: Sí, después de esperar.

`internal_error`HTTP 500

Qué significa: Algo falló de nuestro lado.
Qué hacer: Reintentá con espera creciente. Si se repite, escribinos con el request_id.
¿Reintentar?: Sí, después de esperar.

`service_unavailable`HTTP 503

Qué significa: La API no está disponible en este momento.
Qué hacer: Reintentá con espera creciente. No es un problema de tu credencial.
¿Reintentar?: Sí, después de esperar.

Errores del token

error	HTTP	Cuándo
`invalid_request`	400	Falta `grant_type`, un parámetro vino dos veces, la credencial vino por Basic y en el cuerpo, o el cuerpo no es un formulario ni JSON.
`invalid_client`	401	La credencial no existe, el secreto no coincide o fue revocada. Trae `WWW-Authenticate: Basic`.
`unsupported_grant_type`	400	El `grant_type` no es `client_credentials`.
`invalid_scope`	400	Pediste un permiso que la credencial no tiene (o la credencial no tiene ninguno).
`unauthorized_client`	400	La cuenta no tiene la API habilitada.

Cómo manejarlos

4xx (salvo 401 y 429): el pedido está mal. Reintentarlo igual da lo mismo. Logueá code, detail y request_id.
401: pedí un token nuevo y repetí una sola vez.
429: esperá Retry-After segundos. Ver Límites de uso.
5xx: reintentá con espera creciente (2, 4, 8… segundos) y un tope de intentos. Todas las rutas de lectura se pueden repetir sin riesgo; el PATCH también (deja el mismo código).

invalid_requestHTTP 400

invalid_cursorHTTP 400

unauthorizedHTTP 401

insufficient_scopeHTTP 403

forbiddenHTTP 403

not_foundHTTP 404

method_not_allowedHTTP 405

conflictHTTP 409

goneHTTP 410

unsupported_media_typeHTTP 415

rate_limitedHTTP 429

internal_errorHTTP 500

service_unavailableHTTP 503

invalid_requestHTTP 400

invalid_cursorHTTP 400

unauthorizedHTTP 401

insufficient_scopeHTTP 403

forbiddenHTTP 403

not_foundHTTP 404

method_not_allowedHTTP 405

conflictHTTP 409

goneHTTP 410

unsupported_media_typeHTTP 415

rate_limitedHTTP 429

internal_errorHTTP 500

service_unavailableHTTP 503

`invalid_request`HTTP 400

`invalid_cursor`HTTP 400

`unauthorized`HTTP 401

`insufficient_scope`HTTP 403

`forbidden`HTTP 403

`not_found`HTTP 404

`method_not_allowed`HTTP 405

`conflict`HTTP 409

`gone`HTTP 410

`unsupported_media_type`HTTP 415

`rate_limited`HTTP 429

`internal_error`HTTP 500

`service_unavailable`HTTP 503

`invalid_request`HTTP 400

`invalid_cursor`HTTP 400

`unauthorized`HTTP 401

`insufficient_scope`HTTP 403

`forbidden`HTTP 403

`not_found`HTTP 404

`method_not_allowed`HTTP 405

`conflict`HTTP 409

`gone`HTTP 410

`unsupported_media_type`HTTP 415

`rate_limited`HTTP 429

`internal_error`HTTP 500

`service_unavailable`HTTP 503