Xətalar

Xətalar həmişə RFC 9457 application/problem+json formatında gəlir:

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json

{
  "type": "https://docs.grem.capital/api/errors/business_rule",
  "title": "business_rule",
  "status": 422,
  "detail": "Describe the property: pick a listing or fill in at least a description, city or area",
  "code": "not_enough_input",
  "requestId": "req_..."
}

Sahələrlə validasiya xətası:

{
  "title": "validation",
  "status": 400,
  "detail": "\"avatarId\" is required",
  "errors": [{ "field": "avatarId", "message": "\"avatarId\" is required" }],
  "requestId": "req_..."
}

Xəta kodları

type URL-i bu siyahının uyğun bəndinə aparır.

invalid_key

401. Açar yoxdur, yanlışdır, ləğv edilib və ya müddəti bitib. Authorization başlığını və kabinetdə açarın statusunu yoxlayın.

forbidden_scope

403. Açar etibarlıdır, lakin lazımi icazəsi yoxdur. İcazəni verin və ya yeni açar yaradın (Autentifikasiya).

forbidden

403. Əməliyyat bu hesab və ya resurs üçün icazəli deyil: məsələn, obyekt başqa hesaba məxsusdur və ya agentlikdəki rol kifayət qədər yüksək deyil. Səbəb detail sahəsindədir.

insufficient_funds

402. Cüzdanda kifayət qədər vəsait yoxdur, tarif kvotası tükənib, ödənilməmiş borc var və ya ədalətli istifadə (fair use) limitinə çatılıb. Hansı olduğunu code göstərir: INSUFFICIENT_FUNDS, QUOTA_EXCEEDED, DEBT_OUTSTANDING, FAIR_USE_LIMIT_REACHED və s. Balansı artırın, borcu ödəyin və ya tarifi dəyişin.

validation

400. Sorğu validasiyadan keçmədi. Konkret nəyin səhv olduğu detail və errors sahələrindədir. Sorğunu düzəldin; onu dəyişmədən təkrarlamağın mənası yoxdur.

business_rule

422. Sorğu düzgün tərtib olunub, lakin yerinə yetirilə bilməz: məlumat çatışmır, obyekt uyğun olmayan vəziyyətdədir, obyekt növü dəstəklənmir və s. Səbəb detail sahəsində, maşın kodu isə code sahəsindədir.

payload_too_large

413. Sorğunun gövdəsi və ya fayl limiti aşır. Ölçü limitləri hər alətin təsvirində göstərilib. Etibarlı JSON olmayan gövdə 400 validation qaytarır.

range_not_satisfiable

416. Fayl endirilərkən Range faylın hüdudlarından kənardadır. Content-Range: bytes */size faylın ölçüsünü göstərir.

rate_limited

429. Sorğu limiti aşılıb. Retry-After göstərdiyi qədər saniyə gözləyin, sonra təkrarlayın (Limitlər və ödəniş). Hansı limit olduğunu code göstərir: minute_limit (saniyələr) və ya daily_limit (00:00 UTC-də sıfırlanır).

not_found

404. Naməlum yol və ya mövcud olmayan, yaxud sizə məxsus olmayan resurs. Başqasının resursu üçün qəsdən mövcud olmayan resursla eyni cavab verilir.

idempotency_conflict

409. Bu Idempotency-Key ilə sorğu hələ icra olunur. Onun bitməsini gözləyin və eyni açarla təkrarlayın (İdempotentlik). Taymautdan sonra (502 provider_error) açar 15 dəqiqə saxlanılır: təkrarlamazdan əvvəl nəticəni yoxlayın - saxlama müddətindən sonra təkrar sorğu ödənişli işi yenidən icra edir. Ekspress qiymətləndirmə taymautdan sonra açarı azad edir: onu eyni açarla təkrarlayın. Eyni 409 bu açarla çağırış üçün ödəniş hələ rezerv edilərkən də gəlir (code RESERVE_IN_PROGRESS, RESERVE_BUSY) - sonra təkrarlayın; RESERVE_REF_TAKEN - açar artıq istifadə olunub, yenisini göndərin.

conflict

409. Resurs bu əməliyyata imkan verməyən vəziyyətdədir (məsələn, obyektin agentliklər arasında köçürülməsi, aktiv komissiya müqaviləsi olan obyektin silinməsi). Səbəb detail sahəsindədir. Sorğunu dəyişmədən təkrarlamayın.

service_unavailable

503. Alət müvəqqəti olaraq əlçatan deyil. Heç nə üçün ödəniş tutulmayıb. Retry-After fasiləsindən sonra təkrarlayın; GET /tools/status alətlərin cari vəziyyətini göstərir.

provider_error

502. İşi görən xidmət uğursuz oldu. Bu müvəqqətidir: artan fasilə ilə təkrarlayın. Əgər detail alətin vaxtında cavab vermədiyini bildirirsə, iş yenə də bitə və ödənişli ola bilər: onu yenidən başlatmazdan əvvəl GET /works yoxlayın; ekspress qiymətləndirməni eyni Idempotency-Key ilə təkrarlayın. Fotoların yaxşılaşdırılması, sayt və qaralama nəticələri GET /works daxilində saxlanılmır: onlar üçün 15 dəqiqəlik saxlama müddətini gözləyin və nəticəni kabinetdə və ya obyektləriniz arasında yoxlayın.

internal_error

500. Daxili xəta. Fasilə ilə təkrarlayın; təkrarlanmağa davam edərsə, requestId ilə dəstəyə müraciət edin.

Siyahı genişlənə bilər. Naməlum kodu onun HTTP sinfinin ümumi xətası kimi qəbul edin (4xx - sorğuda problem, 5xx - xidmətdə nasazlıq).

Nəyi təkrarlamaq olar

Nəsə yaradan sorğuları təkrarlayarkən həmişə eyni Idempotency-Key göndərin - onda təkrar sorğu işi nə ikinci dəfə icra edəcək, nə də ikinci dəfə ödəniş tutacaq.

İstisnalar

• Lidin cari vəziyyətinin icazə vermədiyi Swipe Match hadisələri (POST /match/leads/{id}/events) title: business_rule ilə 409 qaytarır, səbəb isə code sahəsindədir (client_event_rejected, invalid_transition, not_available).
• Şəxsi açarla və ya kifayət etməyən rolla agentliyin ümumi lid siyahısı üzrə əməliyyatlar (POST /leads/{id}/claim, POST /leads/{id}/return-to-pool) title: forbidden ilə 403 qaytarır.

Nə üçün ödəniş tutulmur

Rədd edilmiş sorğu (istənilən 4xx və ya 5xx cavabı) API çağırışı sərf etmir. Alətin qiyməti yalnız qəbul edilmiş iş üçün tutulur. İstisna taymautdan sonra provider_error halıdır: iş yenə də bitə və ödənişli ola bilər - onu yenidən başlatmazdan əvvəl GET /works yoxlayın (fotoların yaxşılaşdırılması, sayt və qaralama: kabinet və ya obyektləriniz).

Əlaqəli

• Limitlər və ödəniş
• İdempotentlik
• Autentifikasiya