Errores y límites

Forma de un error

Un error devuelve un código HTTP y un objeto error: code identifica el caso, message lo explica en inglés y details.field nombra el campo erróneo cuando lo hay (links[1].title en un envío agrupado).

curl -X POST https://api.tinylink.fr/v1/tags \
  -H "Authorization: Bearer tl_tu_token" \
  -H "Content-Type: application/json" \
  -d '{"color":"#1E90FF"}'

const response = await fetch('https://api.tinylink.fr/v1/tags', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer tl_tu_token',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ color: '#1E90FF' }),
});
const data = await response.json();

$ch = curl_init('https://api.tinylink.fr/v1/tags');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer tl_tu_token', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode(['color' => '#1E90FF']),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);

import requests

response = requests.post(
    'https://api.tinylink.fr/v1/tags',
    headers={'Authorization': 'Bearer tl_tu_token'},
    json={'color': '#1E90FF'},
)
data = response.json()

Respuesta 422

{
  "error": {
    "code": "validation_failed",
    "message": "The \"name\" field is required.",
    "details": {
      "field": "name"
    }
  }
}

Códigos de error

• 400 — invalid_json: el cuerpo no es un objeto JSON
• 401 — missing_token, invalid_token (token desconocido o revocado), token_owner_lost_access (la persona que lo generó ya no es administradora del espacio de trabajo)
• 403 — insufficient_scope (falta un ámbito, nombrado en details.required_scope), plan_limit_reached (límite del plan alcanzado), plan_required (plan sin API), account_not_verified, account_disabled, forbidden
• 404 — not_found (ruta desconocida, o elemento ausente del espacio de trabajo), qr_code_not_generated
• 405 — method_not_allowed: la cabecera Allow lista los métodos aceptados
• 409 — slug_taken: dirección personalizada ya en uso
• 422 — validation_failed (campo ausente o no válido), invalid_url, suspicious_url (dirección marcada como sospechosa), too_many_blocks
• 423 — element_blocked (elemento bloqueado por la moderación), environment_blocked
• 429 — rate_limited (demasiadas peticiones), too_many_failed_attempts (demasiados tokens no válidos desde la misma dirección)
• 500 — internal_error, qr_code_failed: vuelve a intentarlo más tarde

Límite de peticiones

Cada token tiene derecho a 120 peticiones por minuto. Cada respuesta lleva tres cabeceras: X-RateLimit-Limit, X-RateLimit-Remaining (lo que queda en el minuto) y X-RateLimit-Reset (la hora de puesta a cero, en segundos Unix). Pasado ese límite, la API responde 429 con una cabecera Retry-After.

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 83
X-RateLimit-Reset: 1791230280

Comprobación de los contenidos

Los contenidos creados por la API pasan por la misma comprobación que los de la aplicación: una página, un enlace o un enlace corto puede aparecer con el status pending_review mientras se realiza, y luego active o blocked. Un elemento bloqueado ya no se puede modificar.

Si cambia tu plan

El token sigue al plan del propietario del espacio de trabajo. Si este pasa a un plan sin API, el token queda suspendido: la tarjeta lo indica y cada llamada responde 403 plan_required. No se elimina y se reactiva en cuanto se vuelve a un plan Pro o Business. Un administrador puede revocarlo en cualquier momento, con plan o sin él.