Erreurs et limites

Forme d'une erreur

Une erreur rend un code HTTP et un objet error : code identifie le cas, message l'explique en anglais, et details.field nomme le champ fautif quand il y en a un — links[1].title dans un envoi groupé.

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

const response = await fetch('https://api.tinylink.fr/v1/tags', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer tl_votre_jeton',
    '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_votre_jeton', '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_votre_jeton'},
    json={'color': '#1E90FF'},
)
data = response.json()

Réponse 422

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

Codes d'erreur

• 400 — invalid_json : le corps n'est pas un objet JSON
• 401 — missing_token, invalid_token (jeton inconnu ou révoqué), token_owner_lost_access (la personne qui l'a généré n'est plus admin de l'environnement)
• 403 — insufficient_scope (portée manquante, nommée dans details.required_scope), plan_limit_reached (plafond de l'offre atteint), plan_required (offre sans API), account_not_verified, account_disabled, forbidden
• 404 — not_found (route inconnue, ou élément absent de l'environnement), qr_code_not_generated
• 405 — method_not_allowed : l'en-tête Allow liste les méthodes acceptées
• 409 — slug_taken : adresse personnalisée déjà prise
• 422 — validation_failed (champ manquant ou invalide), invalid_url, suspicious_url (adresse signalée comme suspecte), too_many_blocks
• 423 — element_blocked (élément bloqué par la modération), environment_blocked
• 429 — rate_limited (trop de requêtes), too_many_failed_attempts (trop de jetons invalides depuis la même adresse)
• 500 — internal_error, qr_code_failed : réessayez plus tard

Limite de requêtes

Chaque jeton a droit à 120 requêtes par minute. Chaque réponse porte trois en-têtes : X-RateLimit-Limit, X-RateLimit-Remaining (ce qu'il reste dans la minute) et X-RateLimit-Reset (l'heure de remise à zéro, en secondes Unix). Au-delà, l'API répond 429 avec un en-tête Retry-After.

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

Vérification des contenus

Les contenus créés par l'API passent par la même vérification que ceux de l'application : une page, un lien ou un lien réduit peut apparaître avec le status pending_review le temps qu'elle se fasse, puis active ou blocked. Un élément bloqué ne se modifie plus.

Si votre offre change

Le jeton suit l'offre du propriétaire de l'environnement. S'il passe à une offre sans API, le jeton est suspendu : la carte l'indique et chaque appel répond 403 plan_required. Il n'est pas supprimé et reprend dès le retour à une offre Pro ou Business. Un admin peut le révoquer à tout moment, offre ou pas.