Klaidos
Vieningas klaidų formatas, visų kodų katalogas ir pakartojimų matrica.
Klaidos formatas
Kiekviena 4xx ir 5xx klaida turi tą patį JSON formatą. Pavyzdys su antrašte Accept-Language: lt:
{
"type": "error",
"error": {
"type": "invalid_request_error",
"code": "invalid_parameter",
"message": "limit turi būti nuo 1 iki 100.",
"param": "limit",
"doc_url": "https://diko.app/api-docs/klaidos#invalid_parameter"
},
"request_id": "req_QBPIQ5QTIWAUYTMDNCLD7CMKBE"
}| Laukas | Reikšmė |
|---|---|
type |
visada error |
error.type |
klaidos klasė, pavyzdžiui, invalid_request_error |
error.code |
stabilus mašininis kodas. Visi kodai aprašyti kodų kataloge |
error.message |
žmogui skirtas paaiškinimas |
error.param |
klaidingo parametro pavadinimas, kai taikoma |
error.doc_url |
nuoroda į šio kodo aprašą su inkaru #kodas. Su Accept-Language: lt ji veda į šį puslapį (https://diko.app/api-docs/klaidos#kodas), kitaip į angliškąjį. Senesnė nuoroda /api-docs/errors#kodas nukreipia čia ir išlaiko inkarą |
error.details |
papildomas kontekstas tik tada, kai aktualu: required_scopes, granted_scopes, required_plans, policy (užklausų ribos), limit (kurią importų ribą pasiekė queue_limit_exceeded), retry_after |
request_id |
užklausos ID (req_...). Nurodykite jį kreipdamiesi į pagalbą |
Klasės ir HTTP statusai
Antraštės, kurias verta skaityti
| Antraštė | Kada | Ką daryti |
|---|---|---|
Request-Id (ir X-Request-ID) |
visada | išsaugokite žurnale; ji identiška laukui request_id |
X-Client-Request-Id |
kai ją atsiuntėte | Diko grąžina atgal tą reikšmę, kurią atsiuntėte tokio paties pavadinimo užklausos antraštėje (1–128 simboliai iš A-Za-z0-9._:-; kita reikšmė ignoruojama). Pagal ją suderinsite atsakymą su savo žurnalo įrašu |
Retry-After |
429, 503 ir idempotency_in_progress |
palaukite tiek sveikų sekundžių (bent 1) |
WWW-Authenticate |
401 ir insufficient_scope |
nurodo Bearer realm="diko"; insufficient_scope atveju dar ir reikiamą scope |
Allow |
405 | nurodo leidžiamus metodus |
Pakartojimo matrica
Kartokite tik tada, kai tai prasminga. Klaidos, kurias sukelia pati užklausa, nepasitaiso nuo pakartojimo.
| Situacija | Kartoti? | Kaip |
|---|---|---|
| Tinklo klaida arba baigėsi skirtasis laikas (atsakymo negauta) | taip | eksponentinė pauzė su atsitiktine paklaida; POST visada su tuo pačiu Idempotency-Key |
408 request_timeout |
taip | turinys nepasiekė per ribotą laiką (numatyta 10 s); užklausa nieko nesukūrė, todėl siųskite tą pačią užklausą su tuo pačiu Idempotency-Key. Jei kartojasi, patikrinkite ryšį ir siųskite turinį vienu metu |
| 400, 404, 405, 413, 415, 422 | ne | ištaisykite užklausą (parametrus, ID, užklausos turinį, Content-Type, Idempotency-Key) |
| 401, 403 | ne | patikrinkite raktą, leidimus, planą, IP ir paskyros būseną |
| 402 | ne, kol neišspręsta | apmokėkite planą ar papildykite kreditus; tada užklausą galima kartoti |
409 idempotency_in_progress |
taip, po Retry-After |
ta pati užklausa su tuo pačiu raktu |
409 resource_not_ready |
taip, vėliau | palaukite meeting.ready arba tikrinkite transcript.status |
409 transcript_changed |
taip, iš naujo | pradėkite skaityti be cursor |
409 import_not_cancelable |
ne | importas jau baigtas |
| 429 | taip, po Retry-After |
niekada ne greičiau; naudokite eksponentinę pauzę |
| 500 | taip, 2–3 kartus | su eksponentine pauze; jei kartojasi, praneškite su request_id |
| 503 | taip, po Retry-After |
writes_disabled atveju paprastai po 300 s |
404 api_disabled |
vėliau | API laikinai išjungtas |
Pakartojimo pavyzdys
Šis pagalbinis kodas kartoja 408, 429, 500 ir 503 ir atsižvelgia į Retry-After. Kitu atveju jis naudoja eksponentinę pauzę su atsitiktine paklaida. POST užklausoms perduokite tą patį Idempotency-Key visiems bandymams.
import random
import time
import requests
RETRYABLE = {408, 429, 500, 503}
def request_with_retry(method, url, *, max_attempts=5, **kwargs):
for attempt in range(1, max_attempts + 1):
try:
response = requests.request(method, url, timeout=30, **kwargs)
except (requests.ConnectionError, requests.Timeout):
if attempt == max_attempts:
raise
delay = min(2**attempt, 30)
else:
if response.status_code not in RETRYABLE or attempt == max_attempts:
return response
retry_after = response.headers.get("Retry-After", "")
delay = int(retry_after) if retry_after.isdigit() else min(2**attempt, 30)
time.sleep(delay + random.uniform(0, delay * 0.2))const RETRYABLE = new Set([408, 429, 500, 503])
async function requestWithRetry(url: string, init: RequestInit, maxAttempts = 5): Promise<Response> {
for (let attempt = 1; ; attempt++) {
let delay: number
try {
const response = await fetch(url, { ...init, signal: AbortSignal.timeout(30_000) })
if (!RETRYABLE.has(response.status) || attempt >= maxAttempts) return response
const retryAfter = Number(response.headers.get("Retry-After"))
delay = Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter : Math.min(2 ** attempt, 30)
} catch (error) {
if (attempt >= maxAttempts) throw error
delay = Math.min(2 ** attempt, 30)
}
await new Promise(resolve => setTimeout(resolve, (delay + Math.random() * delay * 0.2) * 1000))
}
}Kodų katalogas
Kiekvienas kodas turi savo inkarą, pavyzdžiui, #invalid_parameter, kad nuoroda doc_url atvestų tiesiai į jo aprašą.
| Kodas | HTTP | Tipas | Kartoti |
|---|---|---|---|
invalid_request | 400 | invalid_request_error | ne |
invalid_parameter | 400 | invalid_request_error | ne |
invalid_cursor | 400 | invalid_request_error | ne |
invalid_youtube_url | 400 | invalid_request_error | ne |
api_key_in_query | 400 | invalid_request_error | ne |
idempotency_key_invalid | 400 | invalid_request_error | ne |
missing_api_key | 401 | authentication_error | ne |
invalid_api_key | 401 | authentication_error | ne |
api_key_expired | 401 | authentication_error | ne |
api_key_revoked | 401 | authentication_error | ne |
api_key_disabled | 401 | authentication_error | ne |
subscription_required | 402 | billing_error | ne |
insufficient_credits | 402 | billing_error | ne |
team_member_limit_reached | 402 | billing_error | ne |
insufficient_scope | 403 | permission_error | ne |
plan_required | 403 | permission_error | ne |
ip_not_allowed | 403 | permission_error | ne |
account_disabled | 403 | permission_error | ne |
email_not_verified | 403 | permission_error | ne |
api_access_suspended | 403 | permission_error | ne |
team_member_disabled | 403 | permission_error | ne |
not_found | 404 | not_found_error | ne |
route_not_found | 404 | not_found_error | ne |
api_disabled | 404 | not_found_error | sąlygiškai |
method_not_allowed | 405 | invalid_request_error | ne |
idempotency_in_progress | 409 | conflict_error | taip, po Retry-After |
import_not_cancelable | 409 | conflict_error | ne |
transcript_changed | 409 | conflict_error | sąlygiškai |
resource_not_ready | 409 | conflict_error | taip |
request_timeout | 408 | invalid_request_error | taip |
request_too_large | 413 | request_too_large | ne |
unsupported_media_type | 415 | invalid_request_error | ne |
idempotency_key_reused | 422 | invalid_request_error | ne |
rate_limit_exceeded | 429 | rate_limit_error | taip, po Retry-After |
queue_limit_exceeded | 429 | rate_limit_error | taip, po Retry-After |
internal_error | 500 | api_error | sąlygiškai |
service_unavailable | 503 | service_unavailable_error | taip, po Retry-After |
credit_balance_unavailable | 503 | service_unavailable_error | taip, po Retry-After |
writes_disabled | 503 | service_unavailable_error | taip, po Retry-After |
invalid_request
Užklausa neatitinka formato: užklausos turinys nėra tinkamas JSON, jo nėra, jis nėra JSON objektas arba Content-Length nėra skaičius. Trūkstamas privalomas laukas ar nežinomas laukas yra invalid_parameter.
Ką daryti. Siųskite JSON objektą ir palyginkite jį su endpointo schema.
invalid_parameter
Kelio, užklausos ar turinio parametro reikšmė netinkama, privalomo lauko trūksta arba laukas nežinomas (nežinomi laukai atmetami). Lauke error.param nurodytas parametras.
Ką daryti. Ištaisykite parametrą pagal jo apribojimus, pavyzdžiui, limit turi būti nuo 1 iki 100.
invalid_cursor
cursor sugadintas arba išduotas kitam naudotojui, maršrutui, rūšiavimui ar filtrams.
Ką daryti. Pradėkite puslapiavimą iš naujo be cursor ir nekeiskite filtrų tarp puslapių.
invalid_youtube_url
URL nėra palaikomas vieno YouTube vaizdo įrašo adresas.
Ką daryti. Naudokite nuorodą iš youtube.com, www.youtube.com, m.youtube.com, music.youtube.com arba youtu.be.
api_key_in_query
Raktas perduotas užklausos eilutėje (api_key, key, token arba access_token).
Ką daryti. Siųskite raktą tik antraštėje Authorization: Bearer. Raktas galėjo patekti į žurnalus, todėl pakeiskite raktą (rotacija).
idempotency_key_invalid
Idempotency-Key netinkamas: reikia 8–255 simbolių iš aibės A-Z a-z 0-9 _ - : ..
Ką daryti. Sugeneruokite UUID ir siųskite jį be papildomų simbolių.
missing_api_key
Užklausoje nėra antraštės Authorization.
Ką daryti. Pridėkite antraštę Authorization: Bearer dk_live_....
invalid_api_key
Antraštė netinkama (ne Bearer schema, tuščias raktas arba kelios antraštės Authorization) arba raktas nežinomas ar blogo formato (neatitinka struktūros ar kontrolinės sumos). Atsakymas visais šiais atvejais vienodas.
Ką daryti. Siųskite vieną antraštę Authorization: Bearer <raktas> ir patikrinkite, ar nukopijavote visą raktą be tarpų. Jei raktas prarastas, sukurkite naują.
api_key_expired
Rakto galiojimas pasibaigė.
Ką daryti. Sukurkite naują raktą Diko programėlėje ir atnaujinkite savo sistemas.
api_key_revoked
Raktas atšauktas: rankiniu būdu, pasibaigus rotacijos persidengimui, dėl nutekėjimo arba išjungus paskyrą.
Ką daryti. Sukurkite naują raktą ir atnaujinkite savo sistemas. Atšaukto rakto atkurti negalima.
api_key_disabled
Raktas laikinai išjungtas.
Ką daryti. Įjunkite raktą Diko programėlėje (reikia pakartotinio patvirtinimo) arba naudokite kitą raktą.
subscription_required
Paskyra neturi aktyvios apmokėtos prieigos.
Ką daryti. Pasirinkite planą Diko programėlėje. API prieinamas Verslo plane.
insufficient_credits
Importui nepakanka kreditų.
Ką daryti. Papildykite kreditus ir pakartokite užklausą. Atsakymas 402 neišsaugomas, todėl galite naudoti tą patį Idempotency-Key.
team_member_limit_reached
Pasiekta jūsų kreditų riba komandoje.
Ką daryti. Paprašykite komandos savininko ar administratoriaus padidinti ribą.
insufficient_scope
Raktas neturi endpointui reikalingo leidimo. error.details turi required_scopes ir granted_scopes.
Ką daryti. Sukurkite raktą su reikiamu leidimu. Leidimai po sukūrimo nekeičiami.
plan_required
Planas neapima API. error.details.required_plans yra verslas.
Ką daryti. Pereikite į planą „Verslas“. Raktai nešalinami ir vėl veikia, kai planas leidžia.
ip_not_allowed
Raktas turi IP apribojimą, o užklausos IP nėra sąraše arba jo nepavyksta nustatyti patikimai.
Ką daryti. Siųskite iš leidžiamo adreso arba pakeiskite sąrašą Diko programėlėje. Patikrinkite IP su kitu raktu be apribojimo: GET /me → request.
account_disabled
Paskyra išjungta.
Ką daryti. Susisiekite su Diko pagalba ir nurodykite request_id.
email_not_verified
Paskyros el. paštas nepatvirtintas.
Ką daryti. Patvirtinkite el. paštą Diko programėlėje.
api_access_suspended
Diko administratorius sustabdė šios paskyros API prieigą.
Ką daryti. Susisiekite su Diko pagalba ir nurodykite request_id.
team_member_disabled
Jūsų narystė komandoje išjungta.
Ką daryti. Susisiekite su komandos savininku ar administratoriumi.
not_found
Resurso nėra, jis nepriklauso jūsų paskyrai arba ID užkoduotas neteisingai.
Ką daryti. Patikrinkite ID. API tyčia grąžina 404, o ne 403, kad nebūtų atskleista, ar svetimas resursas egzistuoja.
route_not_found
Tokio kelio nėra. Kelias su galiniu / taip pat laikomas neegzistuojančiu.
Ką daryti. Patikrinkite kelią ir bazinį URL https://api.diko.app/api/v1.
api_disabled
Viešas API šiuo metu išjungtas.
Ką daryti. Pabandykite vėliau. Jei išjungimas užsitęsia, susisiekite su Diko pagalba.
method_not_allowed
Metodas šiam keliui nepalaikomas. Antraštė Allow nurodo leidžiamus metodus. OPTIONS taip pat grąžina 405, nes naršyklės užklausos nepalaikomos.
Ką daryti. Naudokite vieną iš metodų, nurodytų Allow antraštėje.
idempotency_in_progress
Ta pati užklausa su tuo pačiu Idempotency-Key dar vykdoma.
Ką daryti. Palaukite Retry-After sekundžių ir siųskite identišką užklausą su tuo pačiu raktu.
import_not_cancelable
Importas jau baigtas (succeeded arba failed) ir nebegali būti atšauktas.
Ką daryti. Perskaitykite importo būseną. Jau atšauktas importas (canceling, canceled) grąžina 200.
transcript_changed
Transkriptas pasikeitė puslapiuojant: pasikeitė revision.
Ką daryti. Pradėkite skaityti transkriptą iš naujo be cursor.
resource_not_ready
Transkripto dar nėra: susitikimas vis dar apdorojamas.
Ką daryti. Patikrinkite transcript.status susitikime arba palaukite įvykio meeting.ready, tada bandykite vėl.
request_timeout
Užklausos turinys nebuvo gautas per ribotą laiką (numatyta 10 s). Taip nutinka, kai klientas siunčia turinį per lėtai arba sustoja per siuntimą. Nieko nesukurta.
Ką daryti. Siųskite visą turinį iškart ir patikrinkite ryšį. Užklausą saugu kartoti su tuo pačiu Idempotency-Key.
request_too_large
Užklausos turinys didesnis nei 64 KB.
Ką daryti. Sumažinkite turinį. Šiems endpointams didelio turinio nereikia.
unsupported_media_type
POST užklausos turinys turi būti application/json.
Ką daryti. Nustatykite antraštę Content-Type: application/json.
idempotency_key_reused
Tas pats Idempotency-Key panaudotas su kitu metodu, keliu ar turiniu.
Ką daryti. Kiekvienai naujai operacijai generuokite naują raktą. Kartokite tik identišką užklausą.
rate_limit_exceeded
Viršyta ribų politika. error.details.policy nurodo, kuri.
Ką daryti. Palaukite Retry-After sekundžių. Kartokite su eksponentine pauze su atsitiktine paklaida (angl. exponential backoff with jitter), o ne iškart.
queue_limit_exceeded
Pasiekta importų talpa: iki 10 aktyvių vienam naudotojui, 200 iš viso arba 500 per parą.
Ką daryti. Palaukite Retry-After (60 s) arba kol dalis importų baigsis. Nesiųskite daugiau užklausų, kol eilė pilna.
internal_error
Vidinė serverio klaida.
Ką daryti. Kartokite iki 2–3 kartų su eksponentine pauze su atsitiktine paklaida (POST su tuo pačiu Idempotency-Key). Jei kartojasi, susisiekite su Diko pagalba ir nurodykite request_id.
service_unavailable
Paslauga laikinai užimta, pavyzdžiui, dėl duomenų bazės apkrovos.
Ką daryti. Palaukite Retry-After sekundžių (paprastai 2) ir bandykite vėl.
credit_balance_unavailable
Kreditų likučio dabar nepavyko nustatyti, todėl importas nepradėtas.
Ką daryti. Palaukite Retry-After sekundžių ir pakartokite užklausą su tuo pačiu Idempotency-Key.
writes_disabled
Rašymo operacijos laikinai išjungtos platformos pusėje. Skaitymas veikia.
Ką daryti. Palaukite Retry-After sekundžių (300) ir pakartokite užklausą su tuo pačiu Idempotency-Key.