Erori și limite de rată

Corpul erorii#

{
  "error": {
    "code": "NOTFOUND",
    "message": "Entry not found",
    "requestId": "0f6c1d2e-3b4a-4c5d-8e9f-a0b1c2d3e4f5"
  }
}

GraphQL raportează erorile de interogare în propriul tablou errors; consultați erorile GraphQL.

Identificatori de cerere#

Fiecare eroare conține requestId, la fel ca meta.requestId în răspunsurile reușite pentru contact și rezervări. Trimiteți propriul antet X-Request-Id și API-ul îl va folosi, astfel încât să puteți corela jurnalele dumneavoastră cu ale noastre. Includeți-l ori de câte ori contactați suportul.

# Send your own id and it comes back as requestId (and in the API's logs)
curl https://api.console.citronos.com/v1/content/nope \
  -H "Authorization: Bearer $CITRON_API_KEY" \
  -H "X-Request-Id: my-site-7f3a"
# {"error":{"code":"NOTFOUND","message":"Collection \"nope\" not found","requestId":"my-site-7f3a"}}

Coduri de status#

Coduri de eroare#

Majoritatea erorilor folosesc un cod generic derivat din status. Câteva endpoint-uri adaugă unul specific. Comparați codurile exact așa cum sunt scrise: cele generice nu au caracter de subliniere.

Erori de validare#

Formularele explică fiecare câmp:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Please check the highlighted fields",
    "details": [{ "field": "email", "message": "Enter a valid email" }],
    "requestId": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f"
  }
}

Endpoint-urile de contact și rezervări validează strict corpul JSON și enumeră fiecare problemă, inclusiv câmpurile pe care nu le acceptă:

{
  "error": {
    "code": "BADREQUEST",
    "message": ["mode must be one of the following values: online, in_office"],
    "details": ["mode must be one of the following values: online, in_office"],
    "requestId": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b"
  }
}

Limite de rată#

• Peste limită, răspunsul este 429. Limitele per IP adaugă Retry-After-short (fereastra de un minut) sau Retry-After-long (fereastra de o oră) cu numărul de secunde de așteptat. Limita per cheie se resetează la începutul minutului următor.
• Serverul propriului site preia de obicei conținutul de pe un singur IP; API-ul de conținut este limitat per cheie, nu per IP, așa că randarea paginilor nu este niciodată încetinită de vizitatori.
• Dacă trimiterile trec prin serverul dumneavoastră, transmiteți mai departe x-forwarded-for, astfel încât fiecare vizitator să aibă propriul buget.
• Folosiți cache de partea dumneavoastră (ETag-uri, revalidare Next.js, webhook-uri) în loc să preluați conținutul la fiecare afișare a paginii.

În SDK#

SDK-ul transformă fiecare corp de eroare într-un CitronError și reîncearcă automat la 429 și 5xx. Consultați erorile în SDK.

import { CitronGraphQLError, isCitronError } from '@citron/sdk';

try {
  await citron.collection('products').get('does-not-exist');
} catch (err) {
  if (err instanceof CitronGraphQLError) {
    console.error(err.errors, err.data); // GraphQL errors and partial data
  } else if (isCitronError(err)) {
    console.error(err.status, err.code, err.message, err.requestId, err.details);
    if (err.isNotFound) { /* render your 404 */ }
    if (err.isRetryable) { /* 0, 408, 429 or 5xx; err.retryAfter when the server said */ }
  } else {
    throw err;
  }
}