Concetti

Errori

Gli errori usano i codici di stato HTTP standard e hanno sempre la stessa struttura JSON.

Formato degli errori#

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "This API key does not have the scope posts:write"
  }
}

code è stabile: usalo nel tuo codice.
message è pensato per le persone e può cambiare.
Alcuni errori aggiungono campi extra accanto a code e message (per esempio il campo non valido di un errore di validazione).

Codici di errore#

Stato	Codice	Significato · cosa fare
400	`VALIDATION_ERROR`	Un parametro o un campo del body manca o non è valido. Correggi la richiesta; non ritentarla così com'è.
400	`INVALID_JSON`	Il body non è un JSON valido. Invia `Content-Type: application/json` e un body valido.
401	`INVALID_API_KEY`	Chiave mancante, malformata o revocata. Controlla l'header `Authorization`.
403	`INSUFFICIENT_SCOPE`	Alla chiave manca lo scope richiesto da questo endpoint. Crea una chiave con gli scope giusti.
403	`DEVELOPER_ACCESS_REVOKED`	L'accesso sviluppatore di questo account è stato sospeso o revocato. Scrivi a developers@linework.app.
403	`PROFILE_INCOMPLETE`	Aggiungi una foto profilo e una copertina all'account prima di usare gli endpoint di scrittura.
403	`CHAT_NOT_ALLOWED`	La regola anti-spam non consente questo messaggio: la persona non ti ha scritto e non ti segue.
403	`CHAT_BLOCKED`	Uno dei due ha bloccato l'altro. Non ritentare.
403	`STORE_BLOCKED`	Questo store ti ha bloccato.
403	`USER_UNAVAILABLE`	L'utente non è disponibile (bloccato, privato o sospeso).
403	`FORBIDDEN`	L'azione non è consentita per questo account (per esempio modificare il post di un altro).
404	`NOT_FOUND`	La risorsa non esiste oppure non puoi vederla.
409	`CONFLICT`	La richiesta è in conflitto con lo stato attuale (per esempio spedire due volte lo stesso ordine).
413	`PAYLOAD_TOO_LARGE`	Il body o il file caricato è troppo grande. Vedi i limiti dei media in Pubblicare post con media.
429	`RATE_LIMITED`	Troppe richieste, oppure una quota giornaliera è esaurita. Attendi `Retry-After`. Vedi Rate limit.
500	`INTERNAL_ERROR`	Qualcosa è andato storto da parte nostra. Riprova più tardi con backoff.

Nel tempo potrebbero essere aggiunti nuovi codici: tratta un codice sconosciuto con il significato generico del suo stato HTTP.

Ritentare o no?#

Stato	Ritentare?
400, 401, 403, 404, 409, 413	No. Prima correggi la richiesta, la chiave o l'account.
429	Sì, dopo `Retry-After`.
500, 502, 503, 504	Sì, con backoff esponenziale. Per le scritture non idempotenti (per esempio `POST /posts`), verifica prima che l'azione non sia già avvenuta.

Esempio di gestione#

const res = await fetch(url, options);
if (!res.ok) {
  const { error } = await res.json().catch(() => ({ error: { code: "UNKNOWN" } }));
  switch (error.code) {
    case "RATE_LIMITED": /* wait Retry-After, then retry */ break;
    case "INVALID_API_KEY":
    case "DEVELOPER_ACCESS_REVOKED": /* stop the bot and alert someone */ break;
    case "CHAT_NOT_ALLOWED": /* skip this user */ break;
    default: throw new Error(`${res.status} ${error.code}: ${error.message}`);
  }
}

r = s.post(url, json=body, timeout=30)  # s = requests.Session() with the Authorization header
if not r.ok:
    err = r.json().get("error", {})
    code = err.get("code")
    if code == "RATE_LIMITED":
        ...  # wait Retry-After, then retry
    elif code in ("INVALID_API_KEY", "DEVELOPER_ACCESS_REVOKED"):
        ...  # stop the bot and alert someone
    elif code == "CHAT_NOT_ALLOWED":
        ...  # skip this user
    else:
        raise RuntimeError(f"{r.status_code} {code}: {err.get('message')}")