Hata modeli
DRAEVA API hata sözleşmesi RFC 9457 Problem Details biçimini kullanır. Problem URI'leri için api.getdraeva.com alan adı yönetim tarafından teyit edilmiştir; runtime status/problem
DRAEVA API hata sözleşmesi RFC 9457 Problem Details biçimini kullanır. Problem URI'leri için api.getdraeva.com alan adı yönetim tarafından teyit edilmiştir; runtime status/problem eşlemeleri ve tam hata şemalarının teknik doğrulaması açık kalmaktadır. Aşağıdaki yanıt sözleşme örneğidir, teknik test sonucu değildir:
Content-Type: application/problem+json
X-Request-Id: 01J8Z...
{
"type": "https://api.getdraeva.com/problems/insufficient-scope",
"title": "Forbidden",
"status": 403,
"detail": "This key does not carry the required scope.",
"instance": "/v1/taxonomy",
"requestId": "01J8Z...",
"requiredScope": "taxonomy:classify"
}
Dallanma kuralı
İstemci detail, title veya deprecated error alanına göre dallanmamalıdır. Kararlı tanımlayıcı type URI'sinin son parçasıdır:
function problemSlug(type: unknown): string {
return typeof type === "string" ? (type.split("/").at(-1) ?? "") : "";
}
Problem kataloğu
| Slug | HTTP | İstemci davranışı |
|---|---|---|
missing-credentials | 401 | Server config'i kontrol et |
invalid-credentials | 401 | Anahtarı doğrula/rotate et |
key-revoked | 401 | Yeni anahtara geç |
key-expired | 401 | Yeni anahtar oluştur |
insufficient-scope | 403 | requiredScope için anahtar yetkilerini kontrol et |
service-disabled | 403 | İlgili servisin anahtarınız için etkin olduğunu kontrol et |
invalid-request | 400 | details alanıyla payload'ı düzelt |
unsupported-media-type | 415 | Desteklenen gerçek dosya formatı gönder |
payload-too-large | 413 | Dosya/piksel/liste boyutunu düşür |
rate-limit-exceeded | 429 | Retry-After sonrasında retry |
quota-exceeded | 429 | quotaResetAt zamanına kadar durdur |
upstream-unavailable | 503 | Sınırlı backoff ile retry |
upstream-failed | 502 | Sınırlı backoff ile retry |
internal-error | 500 | requestId ile destek talebi aç |
generation-failed | 422 | Look Engine kullanıcı/gardırop durumu; engineCode gösterimini işle |
Request ID
Her yanıt X-Request-Id taşır. Geçerli bir X-Request-Id gönderirseniz servis onu korur; aksi halde yeni bir değer üretir.
Güvenli log alanları:
requestId, keyId, HTTP status, problem type, süre, endpoint
Loglanmaması gerekenler:
API secret, Authorization header, görsel/base64, gardırop payload'ı, kullanıcı profili
TypeScript örneği
const response = await fetch(url, options);
if (!response.ok) {
const contentType = response.headers.get("content-type") ?? "";
const problem = contentType.includes("application/problem+json")
? await response.json()
: null;
const requestId = response.headers.get("x-request-id");
const type = problemSlug(problem?.type);
throw new Error(`DRAEVA ${response.status} ${type} requestId=${requestId ?? "unknown"}`);
}
Uygulama son kullanıcıya teknik detail metnini doğrudan göstermek yerine kendi yerelleştirilmiş mesajını göstermelidir.