Geliştirici dokümanlarıBaşlarken
Hatalar
Tek hata formatı, değişmeyen kodlar, net tekrar deneme kuralları.
2xx dışındaki her yanıt aynı yapıdadır. Hata işleme mantığınızı message alanına göre değil, her zaman error.code alanına göre kurun.
{
"error": {
"code": "validation_failed",
"message": "The request is invalid.",
"request_id": "req_8fK2Lq9ZtX4mN7bV1cW3yH6p",
"details": [
{
"path": "items[3].length",
"code": "out_of_range",
"message": "length must be greater than 0."
}
]
}
}| Alan | İçerik |
|---|---|
code | Değişmez, snake_case |
message | İngilizce, loglar için |
request_id | X-Request-Id header'ında da bulunur. Destek ekibine iletin |
details[] | 400/422 yanıtlarında: her sorun için path, code, message |
Kodlar
| Durum | Kod | Anlamı | Ne yapılmalı | Tekrar denenebilir |
|---|---|---|---|---|
| 400 | invalid_json | Gövde geçerli bir JSON değil ya da bir alanın türü yanlış. | İstek gövdesini düzeltin. | Hayır |
| 401 | unauthorized | API anahtarı eksik, hatalı biçimde ya da tanınmıyor. | Authorization: Bearer cd_live_… gönderin; anahtarın eksiksiz kopyalandığını kontrol edin. | Hayır |
| 401 | key_revoked | Anahtar iptal edildi. | Geliştirici konsolunda yeni bir anahtar oluşturun. | Hayır |
| 401 | key_expired | Anahtarın geçerlilik süresi doldu. | Geliştirici konsolunda yeni bir anahtar oluşturun. | Hayır |
| 402 | insufficient_credits | Kullanılabilir krediler, bu işin olabilecek en düşük maliyetini bile karşılamıyor. | Kredi paketi satın alın ya da aylık kredileri bekleyin; herhangi bir ücret alınmadı. | Hayır |
| 403 | ip_not_allowed | İsteği gönderen IP, anahtarın izin listesinde değil. | İsteği izin verilen bir IP'den gönderin ya da IP izin listesini düzenleyin. | Hayır |
| 403 | subscription_inactive | Organizasyonun API'yi içeren etkin bir aboneliği yok. | Aboneliği yenileyin. | Hayır |
| 403 | account_inactive | Organizasyon askıya alınmış ya da hesabı etkin olan bir organizasyon sahibi yok. | Destek ekibiyle iletişime geçin. | Hayır |
| 403 | scope_missing | Anahtarda bu endpoint'in gerektirdiği bir yetki eksik. | Gerekli yetkiye sahip bir anahtar kullanın (pack:write, jobs:read, account:read, resources:read, resources:write). | Hayır |
| 403 | preset_read_only | Hazır araçlar değiştirilemez ve silinemez. | Kendi aracınızı oluşturun: POST /v1/vehicles. | Hayır |
| 403 | plan_limit_reached | Organizasyonun paketi daha fazla proje ya da yük öğesine izin vermiyor. | Artık ihtiyaç duymadığınız projeleri silin ya da daha büyük bir pakete geçin. | Hayır |
| 404 | not_found | Bu metoda ve yola sahip bir /v1 endpoint'i yok. | Metodu ve yolu endpoint listesiyle karşılaştırın. | Hayır |
| 404 | job_not_found | Organizasyonunuzda bu ID'ye sahip bir iş yok. | ID'yi kontrol edin. | Hayır |
| 404 | vehicle_not_found | Hazır araçlar ve organizasyonunuzun araçları arasında bu ID'ye sahip bir araç yok. | ID'yi şu listeyle karşılaştırın: GET /v1/vehicles. | Hayır |
| 404 | template_not_found | Organizasyonunuzda bu ID'ye sahip bir şablon yok. | ID'yi şu listeyle karşılaştırın: GET /v1/templates. | Hayır |
| 404 | project_not_found | Organizasyonunuzda bu ID'ye sahip bir proje yok. | ID'yi şu listeyle karşılaştırın: GET /v1/projects. | Hayır |
| 409 | job_not_finished | İş hâlâ sırada ya da çalışıyor. | status değeri succeeded olana kadar GET /v1/jobs/{id} ile sorgulayın. | Evet |
| 409 | project_busy | Proje şu anda hesaplanıyor (uygulamada ya da başka bir iş tarafından). | Bu hesaplamanın bitmesini bekleyin, sonra tekrar deneyin. | Evet |
| 409 | job_failed | İş başarısız oldu; sonucu yok. | job.error alanına bakın; bizden kaynaklanan hatalar ücretlendirilmez (time_limit_exceeded, iptal edilen bir iş gibi ücretlendirilir). Neden geçiciyse yeniden gönderin. | Hayır |
| 409 | job_canceled | İş iptal edildi; sonucu yok. | Gerekirse yeniden gönderin. | Hayır |
| 409 | job_already_finished | İş zaten bitti, iptal edilemez. | Yapılacak bir şey yok. | Hayır |
| 400 | idempotency_key_invalid | Idempotency-Key header'ı 128 karakterden uzun. | Daha kısa bir anahtar kullanın (UUID uygundur). | Hayır |
| 410 | result_expired | Sonucun saklama süresi doldu ve sonuç silindi. | Plana yeniden ihtiyacınız varsa işi yeniden gönderin. | Hayır |
| 413 | payload_too_large | İstek gövdesi 10 MB sınırını aşıyor. | Daha az ya da daha basit öğe gönderin. | Hayır |
| 422 | validation_failed | İstek geçerli bir JSON ama geçersiz bir iş tanımlıyor. Tüm sorunlar details[] içinde listelenir. | details[].path ile belirtilen her alanı düzeltin; doğrulama hataları ücretsizdir. | Hayır |
| 429 | rate_limited | Geçerli dakika, saat ya da gün içinde çok fazla istek gönderildi (anahtar ya da organizasyon başına) veya IP adresinizden gelen başarısız kimlik doğrulama denemeleri dakikada 60 sınırını aştı. | Retry-After header'ında belirtilen saniye kadar bekleyin, ardından artan bekleme süreleriyle (backoff) tekrar deneyin. | Evet |
| 429 | too_many_jobs | Organizasyonun sıradaki + çalışan iş sayısı zaten üst sınırda. | Çalışan işlerin bitmesini bekleyin, sonra tekrar deneyin. | Evet |
| 500 | internal_error | Bizim tarafımızda bir hata oluştu. | Artan bekleme süreleriyle (backoff) tekrar deneyin; sorun sürerse destek ekibine request_id değerini iletin. | Evet |
| 503 | api_disabled | API geçici olarak devre dışı (bakım) ya da organizasyon için kapatılmış. | Daha sonra tekrar deneyin. | Evet |
Doğrulama ayrıntıları
422 validation_failed yanıtındaki details[].code değerleri:
| Kod | Anlamı |
|---|---|
required | Zorunlu bir alan eksik |
invalid_value | Tür yanlış ya da değer izin verilenlerden biri değil |
out_of_range | Çok küçük, çok büyük ya da çok uzun |
duplicate_id | Bir ID iki kez kullanılmış |
unknown_vehicle | Bu vehicle_id ile bir hazır araç ya da size ait bir araç yok |
unknown_template | Bu template_id ile size ait bir şablon yok |
type_not_allowed | Araç türü organizasyonunuz için etkin değil |
unknown_group | Bir öğe, listede olmayan bir gruba başvuruyor |
does_not_fit | Öğe, listelenen hiçbir araca sığmıyor |
too_many_items | Öğe adedi işin limitini aşıyor |
too_many_vehicles | Araç sayısı işin limitini aşıyor |
unknown_field | API'nin tanımadığı bir alan |
İş hataları
failed ya da canceled durumundaki bir işin nedeni job.error.code alanında yer alır:
| Kod | Anlamı |
|---|---|
canceled | İş şu çağrıyla iptal edildi: DELETE /v1/jobs/{id}. Ücret: iş ücreti + kullanılan hesaplama süresi. |
time_limit_exceeded | Hiçbir araç yüklenmeden hesaplama süresi sınırı doldu. İptal edilen bir iş gibi ücretlendirilir: iş ücreti, büyük yük ek ücreti ve kullanılan hesaplama süresi; araç başı ücret hiçbir zaman alınmaz. |
engine_failed | Yükleme algoritması hata verdi. Ücret alınmaz. |
queue_timeout | İş, hesaplama kapasitesi için çok uzun süre bekledi. Ücret alınmaz. |
server_restarted | İş sıradayken ya da çalışırken servis yeniden başlatıldı. Ücret alınmaz. |
Tekrar denemeler
429, 500 ve 503 yanıtlarını Retry-After değerine uyarak üstel artan bekleme süreleriyle (exponential backoff) tekrar deneyin. Aynı Idempotency-Key değerini gönderin (Idempotency). Diğer 4xx yanıtlarında isteği değiştirmeden asla tekrar denemeyin.