API səhv kodları və ən yaxşı practices

1) Niyə səhvləri standartlaşdırmaq

Müştərilər üçün proqnozlaşdırma: vahid format və retraj davranışı.
Debatın sürətləndirilməsi: 'trace _ id '/' request _ id', sabit 'error _ code'.
Təhlükəsizlik: SQL/stack traces/konfiqlər sızmaz.
Müşahidə: səhvlərin taksonomiyası üzrə hesabat (validasiya, kvota, taymaut və s.).

2) Əsas prinsiplər

1. Bütün 4xx/5xx üçün vahid cavab formatı (və qismən səhvləri olan 2xx üçün - ayrıca sxem).
2. HTTP dəqiq semantikası: düzgün status ən vacibdir.
3. İki səviyyəli kod: nəqliyyat ('status') və sabit domen 'error _ code'.
4. Retriable vs Non-retriable: açıq göstərin və geri off üçün bir ipucu verin.
5. Default təhlükəsizlik: təfərrüatlar - yalnız hüquqlu müştəri; daxili yollar olmadan.
6. Lokalizasiya: maşın kodu sabit qalır, mətn tərcümə olunur.

3) Vahid səhv formatı (RFC 7807 əsasında)

json
{
"type": "https://api. example. com/errors/validation_failed",
"title": "Validation failed",
"status": 422,
"error_code": "VAL_001",
"detail": "Field 'email' must be a valid address",
"instance": "req_01HZY...93",
"trace_id": "a1b2c3d4e5f6",
"retriable": false,
"errors": [
{"field": "email", "code": "email_invalid", "message": "Invalid email"}
],
"hint": "Fix payload and retry",
"meta": {"docs": "https://docs. example. com/errors#VAL_001"}
}

Məcburi: 'type', 'title', 'status', 'error _ code', 'trace _ id'.
Əlavə: 'errors []' (sahələr üzrə), 'retriable', 'hint', 'meta'.

• `Content-Type: application/problem+json`
• `X-Request-ID`/`Traceparent` (W3C)
• (429/503 üçün) 'Retry-After' (saniyə və ya tarix)

4) HTTP status semantikası («klassika» və praktikanın birləşməsi)

2xx (nüanslarla uğur)

200 OK - adi uğur.
201 Created - resurs (Location) yaradılmışdır.
202 Accepted - asenxron (verin 'status _ url').
207 Multi-Status - qismən uğur (mümkünsə çəkinin).

4xx (müştəri səhvi)

400 Bad Request - sintaksis/format, lakin sahələrin validasiyası deyil (daha yaxşı 422).
401 Unauthorized - heç bir/səhv token. Gəlin 'WWW-Authenticate'.
403 Forbidden - validen token, lakin yetərli hüquqlar (RBAC/ABAC/limitlər).
404 Not Found - resurs/end-point yoxdur.
409 Conflict - versiya/vəziyyət toqquşması (optimistic locking, idempotency).
410 Gone - son nöqtə əbədi olaraq silinir.
412 Precondition Failed - ETag/If-Match keçmədi.
415 Unsupported Media Type - səhv 'Content-Type'.
422 Unprocessable Entity - biznes qaydalarının təsdiqi.
429 Too Many Requests - kvota/sürət aşdı (bax § 7).

5xx (server səhvi)

500 Internal Server Error - qəfil səhv; detalları açıqlamayın.
502 Bad Gateway - axın səhvidir.
503 Service Unavailable - deqradasiya/həddindən artıq yükləmə, 'Retry-After' verin.
504 Gateway Timeout - arxa tərəfin vaxtıdır.

5) Domen taksonomiyası 'error _ code'

• 'AUTH _' - autentifikasiya/avtorizasiya.
• 'VAL _' - giriş məlumatlarının validasiyası.
• 'RATELIMIT _' - kvotalar və sürət.
• 'IDEMP _' - idempotentlik/dublikatlar.
• 'CONFLICT _' - versiyalar/vəziyyət.
• 'DEP _' - asılılıqlar (PSP/DNS/SMTP).
• 'PAY _' - ödəniş domeninin biznes səhvləri.
• 'SEC _' - təhlükəsizlik (imzalar, HMAC, mTLS).
• 'INT _' - daxili qəfil.

• Zaman sabitliyi (back-compat).
• Səhv kataloqunda təsvirlər və nümunələr (docs + machine-readable JSON).

6) Retriable vs Non-retriable

• `retriable: true|false`
• Əgər 'true' - mütləq 'Retry-After' (saniyədə) və ya müqavilə «eksponensial geri dönüş (1-2 s, maksimum 30-60 s)».

Retriable adətən: '502/503/504', bəzi '500', '429' (pəncərədən sonra).
Non-retriable: `400/401/403/404/409/410/415/422`.

7) Rate limit & quota səhvlər (429)

json
{
"type": "https://api. example. com/errors/rate_limited",
"title": "Rate limit exceeded",
"status": 429,
"error_code": "RATELIMIT_RPS",
"detail": "Too many requests",
"retriable": true
}

• `Retry-After: 12`
• `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
• Для квот: `X-Quota-Limit`, `X-Quota-Remaining`, `X-Quota-Reset`

8) İdempotentlik və münaqişələr

Qeyd sorğularında - «Idempotency-Key» (24-72 saat ərzində unikaldır).
Yenidən əməliyyat konflikti → 409 Conflict ilə 'error _ code: "IDEMP_REPLAY"'.
ETag → 412 Precondition Failed.
Cavabda təhlükəsiz təkrar sorğu üçün 'resource _ id '/' status _ url' əlavə edin.

9) Validasiya və 422

json
{
"status": 422,
"error_code": "VAL_001",
"errors": [
{"field":"email","code":"email_invalid","message":"Invalid email"},
{"field":"age","code":"min","message":"Must be >= 18"}
]
}

• Eyni şeyi 400 - 422-də təkrarlamayın.
• Mesajlar - insan oxunan; 'code' - maşın.

10) Səhv təhlükəsizliyi

Heç vaxt: stack traces, SQL, fayl yolları, xüsusi hosts adları.
PII-ni redaktə edin; GDPR/DSAR-ı izləyin.
İmza üçün/NMAS: 'SEC _ SIGNATURE _ MISMATCH' (403) və 'SEC _ TIMESTAMP _ SKEW' (401/403) '5 dəq ± vaxtını yoxlayın.

11) Korrelyasiya və müşahidə

Həmişə 'trace _ id '/' X-Request-ID' əlavə edin və qeydlərə/yollara atın.
Səhvlər 'error _ code' və 'status' → dashboard «top səhvlər», «new vs known».
Alertlər: 5xx/422/429 sıçrayış, gecikmə p95, share of errors.

12) gRPC/GraphQL/Webhooks - mappinqlər

gRPC ↔ HTTP

GraphQL

Nəqliyyat 200, lakin 'errors []' daxilində - 'extensions əlavə edin. code` и `trace_id`.
«Fatal» üçün (autentifikasiya/kvota) - daha yaxşı real HTTP 401/403/429.

Webhooks

Yalnız 2xx alıcını uğurlu hesab edin.
«X-Webhook-ID», «X-Signature».
410 alıcıdan - retrayaları dayandırın (endpoint silinir).

13) Səhv versiyası

'type '/' error _ code' - sabit; yeni - yalnız əlavə edin.
Bədən sxemini dəyişdirdikdə - API və ya 'problem + json-un kiçik versiyasını artırın; v=2`.
Sənədləşmə: kodlar cədvəli + nümunələr; səhv changelog.

14) Sənədləşmə (OpenAPI fraqmentləri)

Qlobal cavablar

yaml components:
responses:
Problem:
description: Problem Details content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
schemas:
Problem:
type: object required: [type, title, status, error_code, trace_id]
properties:
type: { type: string, format: uri }
title: { type: string }
status: { type: integer }
error_code: { type: string }
detail: { type: string }
instance: { type: string }
trace_id: { type: string }
retriable: { type: boolean }
errors:
type: array items:
type: object properties:
field: { type: string }
code: { type: string }
message: { type: string }

Endpoint nümunəsi

yaml paths:
/v1/users:
post:
responses:
'201': { description: Created }
'401': { $ref: '#/components/responses/Problem' }
'422': { $ref: '#/components/responses/Problem' }
'429': { $ref: '#/components/responses/Problem' }
'500': { $ref: '#/components/responses/Problem' }

15) Test və keyfiyyət

Müqavilə testləri: uyğunluq 'application/problem + json', məcburi sahələr.
Negative tests: bütün filiallar 401/403/404/ 409/422/429/500.
Chaos/latency: 5xx/ 503/504/429 ('Retry-After') retraylarını yoxlayın.
Təhlükəsizlik testləri: daxili mesajların olmaması, düzgün PII maska.
Backward-compat: Köhnə müştərilər yeni sahələri başa düşürlər (əlavə edin, sındırmayın).

16) Giriş çek siyahısı

• Vahid 'problem + json' + sabit 'error _ code'.
• HTTP/gRPC/GraphQL düzgün semantikası.
• Retriable/non-retriable + 'Retry-After '/back-off tövsiyələri.
• Rate-limit başlıqları və 429 davranış.
• İdempotentlik ('Idempotency-Key', 409/412).
• Təhlükəsizlik: No stack traces/secrets, PII-edition.
• 'trace _ id '/' X-Request-ID' bütün səhvlərdə.
• Səhv kataloqunun sənədləşdirilməsi və nümunələri.
• Səhv taksonomiyası üzrə monitorinq.
• Mənfi ssenarilərin avtostestləri.

17) Mini-FAQ

400 422-dən nə ilə fərqlənir?
400 - sınıq sorğu (sintaksis/məzmun növü). 422 - sintaksis etibarlı, lakin biznes qaydaları keçmədi.

Nə zaman 401, nə zaman 403?
401 - yox/səhv token; 403 - token var, hüquqlar yoxdur.

Həmişə 'Retry-After' lazımdır?
429/503 üçün - bəli; qalanları üçün retriable - açıq tövsiyə vermək məsləhətdir.

Yekun

Yaxşı dizayn edilmiş səhvlər bir müqavilədir: düzgün HTTP statusu, vahid 'problem + json', sabit 'error _ code', retrajlarda aydın ipuçları və ciddi təhlükəsizlik. Formatı standartlaşdırın, taksonomiyanı sənədləşdirin, telemetriya və testlər əlavə edin və API-ləriniz proqnozlaşdırıla bilən, təhlükəsiz və inteqratorlara dost olacaq.