La API de Tutiplay

Errores

Todos los errores comparten formato e incluyen un código estable, que es el dato en el que debe basarse un cliente.

Formato

Todos los errores tienen el mismo formato: un código estable en error y una descripción en message. Algunos incluyen además campos con los datos necesarios para actuar, que se indican en cada caso.

json

{"error":"SCOPE","message":"This API token was not granted the permission this call needs"}

La lógica del cliente debe basarse en el código, nunca en el texto: el mensaje está pensado para una persona y puede cambiar sin previo aviso. Pueden añadirse códigos nuevos; un cliente que reciba uno que no conoce debe tratarlo como el error genérico de su estado HTTP.

API key y permisos

HTTP	error	Significado
`401`	`UNKNOWN`	La API key no existe o ha sido revocada.
`401`	`EXPIRED`	La API key ha caducado.
`401`	`INACTIVE`	La cuenta no está activa.
`403`	`SCOPE`	La llamada requiere un nivel de permiso superior al de la API key.
`403`	`CLOSED`	El endpoint no está disponible para las API keys.

Límites de uso

HTTP	error	Significado
`429`	`TOO_FAST`	Se ha alcanzado el límite de llamadas por minuto a los datos de fútbol. Espera el tiempo indicado en `Retry-After`.
`429`	`DAILY_QUOTA`	Se ha alcanzado el límite diario de llamadas a los datos de fútbol. Espera el tiempo indicado en `Retry-After`.

Validación

HTTP	error	Significado
`400`	`VALIDATION_FAILED`	El cuerpo de la petición no es válido. Incluye `fields`, con cada campo erróneo y el motivo.
`400`	`MALFORMED_REQUEST`	El cuerpo no se puede leer —no es JSON— o un parámetro no es del tipo esperado. No llega a comprobarse ningún campo.

Pronósticos

Guardar, confirmar o deshacer un pronóstico puede devolver estos códigos. Varios comparten estado HTTP, por lo que solo el código permite distinguirlos.

HTTP	error	Significado
`409`	`ROUND_CLOSED`	El plazo de la jornada ha terminado.
`409`	`ALREADY_CONFIRMED`	El pronóstico ya está confirmado y la llamada no pedía confirmarlo.
`409`	`NOT_CONFIRMED`	El pronóstico no está confirmado, así que no hay confirmación que deshacer.
`409`	`SINGLE_FORECAST`	La peña, o esta jornada, solo admite un pronóstico por socio.
`409`	`TOO_MANY_COLUMNS`	Se supera el número de columnas que permite la peña. Incluye `maxColumnsPerMember`.
`409`	`NO_ROOM_FOR_ANOTHER`	No quedan columnas libres para otro pronóstico en esta jornada.
`403`	`NOT_ALLOWED_TO_BET`	Las reglas de la peña no te permiten jugar en ella.
`404`	`NO_FORECAST`	No tienes ningún pronóstico con ese número en esta jornada.
`422`	`FORECAST_INCOMPLETE`	Falta alguna marca o algún lado del pleno al 15.
`422`	`TOO_FEW_COLUMNS`	No se alcanza el mínimo de columnas de la peña. Incluye `minimumColumns`.
`422`	`MULTIPLE_NOT_SUPPORTED`	Hay dos signos en un mismo partido, o dos casillas en un mismo lado del pleno al 15.
`422`	`COLUMN_NUMBERING`	Las columnas deben numerarse desde 1 y sin huecos.
`422`	`FORECAST_NUMBERING`	Los pronósticos deben numerarse desde 1 y sin huecos. Incluye `expected`.

Saldo

HTTP	error	Significado
`402`	`INSUFFICIENT_BALANCE`	El saldo no alcanza para las columnas que se confirman.

Es el único error que se resuelve fuera de la API y después se puede reintentar. Por eso incluye el detalle del importe y, en topUpUrl, la página donde el titular de la cuenta puede recargar saldo. La recarga la hace una persona desde el navegador; un cliente no puede hacerla, pero sí indicar a dónde ir.

json

{
  "error": "INSUFFICIENT_BALANCE",
  "message": "Not enough balance to confirm 2 columns",
  "columns": 2,
  "columnPrice": 1.00,
  "required": 2.00,
  "available": 0.30,
  "missing": 1.70,
  "topUpUrl": "https://…/account/balance"
}

Juego automático

HTTP	error	Significado
`422`	`TEMPLATE_DOES_NOT_FIT`	La plantilla que se intenta asignar con `PUT …/auto-play` no es compatible con las reglas de la peña.

El motivo viene en reason, junto con los datos necesarios para corregirlo: INCOMPLETE, ONE_FORECAST_PER_MEMBER, TOO_FEW_COLUMNS (con minimum) o TOO_MANY_COLUMNS (con limit y columns).

Fallos del servidor

HTTP	error	Significado
`500`	`INTERNAL_ERROR`	Algo ha fallado por nuestra parte. Incluye `reference`, ocho caracteres que identifican ese fallo concreto.

No describe nada, a propósito: si pudiéramos describirlo tendría su propio código. No se puede corregir desde el cliente, así que reintentar al cabo de un momento es lo único que tiene sentido hacer — y si se repite, la reference es lo que nos permite encontrarlo.

json

{
  "error": "INTERNAL_ERROR",
  "message": "Unexpected server error",
  "reference": "ab797f5f"
}

Errores sin código propio

Cuando un error no tiene código propio, error contiene el nombre de su estado HTTP (NOT_FOUND, CONFLICT…).

HTTP	Cuándo se produce
`404`	El recurso no existe o no es visible para tu cuenta. Los dos casos responden igual.
`409`	La operación es incompatible con el estado actual del recurso.
`422`	La petición tiene la forma correcta, pero su contenido no es válido.