Errori e limiti

Forma di un errore

Un errore restituisce un codice HTTP e un oggetto error: code identifica il caso, message lo spiega in inglese, e details.field indica il campo errato quando ce n'è uno — links[1].title in un invio raggruppato.

curl -X POST https://api.tinylink.fr/v1/tags \
  -H "Authorization: Bearer tl_il_tuo_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_il_tuo_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_il_tuo_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_il_tuo_token'},
    json={'color': '#1E90FF'},
)
data = response.json()

Risposta 422

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

Codici di errore

• 400 — invalid_json: il corpo non è un oggetto JSON
• 401 — missing_token, invalid_token (token sconosciuto o revocato), token_owner_lost_access (la persona che lo ha generato non è più amministratore dello spazio di lavoro)
• 403 — insufficient_scope (ambito mancante, indicato in details.required_scope), plan_limit_reached (limite del piano raggiunto), plan_required (piano senza API), account_not_verified, account_disabled, forbidden
• 404 — not_found (route sconosciuta, o elemento assente dallo spazio di lavoro), qr_code_not_generated
• 405 — method_not_allowed: l'intestazione Allow elenca i metodi accettati
• 409 — slug_taken: indirizzo personalizzato già preso
• 422 — validation_failed (campo mancante o non valido), invalid_url, suspicious_url (indirizzo segnalato come sospetto), too_many_blocks
• 423 — element_blocked (elemento bloccato dalla moderazione), environment_blocked
• 429 — rate_limited (troppe richieste), too_many_failed_attempts (troppi token non validi dallo stesso indirizzo)
• 500 — internal_error, qr_code_failed: riprova più tardi

Limite di richieste

Ogni token ha diritto a 120 richieste al minuto. Ogni risposta porta tre intestazioni: X-RateLimit-Limit, X-RateLimit-Remaining (quante ne restano nel minuto) e X-RateLimit-Reset (l'ora di azzeramento, in secondi Unix). Oltre il limite, l'API risponde 429 con un'intestazione Retry-After.

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

Verifica dei contenuti

I contenuti creati dall'API passano per la stessa verifica di quelli dell'applicazione: una pagina, un link o un link breve può comparire con lo status pending_review il tempo che la verifica avvenga, poi active o blocked. Un elemento bloccato non si modifica più.

Se il tuo piano cambia

Il token segue il piano del proprietario dello spazio di lavoro. Se passa a un piano senza API, il token viene sospeso: la scheda lo indica e ogni chiamata risponde 403 plan_required. Non viene eliminato e riprende non appena si torna a un piano Pro o Business. Un amministratore può revocarlo in qualsiasi momento, con o senza piano.