API ýalňyşlyk kodlary we iň gowy amallar

1) Näme üçin ýalňyşlyklary standartlaşdyrmak

Müşderiler üçin öňünden aýdylýanlygy: retraýalaryň ýeke-täk formaty we özüni alyp barşy.
Debagyň tizlenmegi: 'trace _ id '/' request _ id', durnukly 'error _ code'.
Howpsuzlyk: SQL/stack traces/konfigi syzmaz.
Syn edilmegi: ýalňyşlyklaryň taksonomiýasy boýunça hasabat (walidasiýa, kwotalar, wagtlar we ş.m.).

2) Esasy ýörelgeler

1. Hemmeler üçin birmeňzeş jogap formaty 4xx/5xx (we 2xx üçin bölekleýin ýalňyşlyklar - aýratyn shema).
2. HTTP-iň aýdyň semantikasy: dogry status iň möhümdir.
3. Iki derejeli kod: transport ('status') we domen durnukly 'error _ code'.
4. "Retriable vs Non-retriable": aç-açan görkeziň we arka offdan maslahat beriň.
5. Howpsuzlyk: jikme-jiklikler - diňe hukuklary bolan müşderi üçin; içerki ýollarsyz.
6. Lokalizasiýa: maşyn kody durnukly galýar, teksti terjime edýäris.

3) Ýeke-täk ýalňyşlyk formaty (RFC 7807 esasynda)

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"}
}

Hökmany: 'type', 'title', 'status', 'error _ code', 'trace _ id'.
Goşmaça: 'errors []' (meýdanlar boýunça), 'retriable', 'hint', 'meta'.

• `Content-Type: application/problem+json`
• `X-Request-ID`/`Traceparent` (W3C)
• (429/503 üçin) 'Retry-After' (sekunt ýa-da sene)

4) HTTP statuslarynyň semantikasy ("klassikleriň" we tejribäniň birleşmegi)

2xx (nuanslar bilen üstünlik)

200 OK - adaty üstünlik.
201 Created - resurs (Location) döredildi.
202 Accepted - nobata asinxron (beriň 'status _ url').
207 Multi-Status - bölekleýin üstünlik (mümkin bolsa gaça duruň).

4xx (müşderiniň ýalňyşlygy)

400 Bad Request - sintaksis/format, ýöne meýdanlary tassyklamak däl (has gowusy 422).
401 Unauthorized - ýok/nädogry belgi. Geliň 'WWW-Authenticate'.
403 Forbidden - token waliden, ýöne hukuklar ýeterlik däl (RBAC/ABAC/çäklendirmeler).
404 Not Found - çeşme/endpoint ýok.
409 Conflict - wersiýalaryň/ýagdaýyň gapma-garşylygy (optimistic locking, idempotency).
410 Gone - endpoint hemişelik aýrylýar.
412 Precondition Failed - ETag/If-Match geçmedi.
415 Unsupported Media Type - nädogry 'Content-Type'.
422 Unprocessable Entity - iş düzgünleriniň tassyklamasy.
429 Too Many Requests - kwotalardan/tizlikden geçdi (§ 7 serediň).

5xx (serwer hatasy)

500 Internal Server Error - duýdansyz ýalňyşlyk; jikme-jiklikleri aýan etmezlik.
502 Bad Gateway - akymyň ýalňyşlygy.
503 Service Unavailable - degradasiýa/artykmaç ýük, beriň 'Retry-After'.
504 Gateway Timeout - yzyna gaýtarmagyň wagty.

5) Domen taksonomiýasy 'error _ code'

• 'AUTH _' - tassyklamak/ygtyýarlandyrmak.
• 'VAL _' - giriş maglumatlaryny tassyklamak.
• 'RATELIMIT _' - kwotalar we tizlik.
• 'IDEMP _' - idempotentlik/dublikatlar.
• 'CONFLICT _' - wersiýalary/ýagdaýy.
• 'DEP _' - garaşlylyk (PSP/DNS/SMTP).
• 'PAY _' - töleg domeniniň iş ýalňyşlyklary.
• 'SEC _' - howpsuzlyk (gollar, HMAC, mTLS).
• 'INT _' - içerki duýdansyz.

• Wagt durnuklylygy (back-compat).
• Hatalar katalogyndaky düşündirişler we mysallar (docs + machine-readable JSON).

6) Retriable vs Non-retriable

• `retriable: true|false`
• Eger 'true' - hökman 'Retry-After' (sekuntda) ýa-da "eksponensial arka-off (1-2 s, maks. 30-60 s)" şertnamasy.

Retriable adatça: '502/503/504', käbirleri '500', '429' (penjireden soň).
Non-retriable: `400/401/403/404/409/410/415/422`.

7) Rate limit & quota ýalňyşlyklar (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) Idempotentlik we gapma-garşylyklar

Ýazgy haýyşlarynda - "Idempotency-Key" (24-72 sagadyň içinde özboluşly).
Gaýtalanýan amalyň gapma-garşylygy → 409 Conflict with 'error _ code: "IDEMP_REPLAY"'.
ETag → 412 Precondition Failed.
Jogap hökmünde howpsuz gaýtadan soramak üçin 'resource _ id '/' status _ url' goşuň.

9) Tassyklama we 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"}
]
}

• Şol bir zady 400 - 422-de köpeltmäň.
• Habar - adam okalýar; 'code' - maşyn.

10) Ýalňyşlyklaryň howpsuzlygy

Hiç haçan: stack traces, SQL, faýl ýollary, hususy hosts atlary.
PII redaktirläň; GDPR/DSAR-a gözegçilik ediň.
Gol çekmek üçin/NMAS: 'SEC _ SIGNATURE _ MISMATCH' (403) we 'SEC _ TIMESTAMP _ SKEW' (401/403) belgilerini "wagty barlaň ± 5 minut".

11) Baglanyşyk we gözegçilik etmek

Elmydama 'trace _ id '/' X-Request-ID' goşuň we girelgeleriňize/ýollaryňyza zyňyň.
Hatalary 'error _ code' we 'status' → "top-hatalar", "new vs known" dashbordlary boýunça jemläň.
Alertler: 5xx/422/429, gizlinlik p95, share of errors.

12) gRPC/GraphQL/Webhooks - mappingler

gRPC ↔ HTTP

GraphQL

Ulag 200, ýöne 'errors []' içinde - 'extensions' goşuň. code` и `trace_id`.
"Fatal" (kwota) üçin - hakyky HTTP 401/403/429 has gowudyr.

Webhooks

Diňe 2xx alyjyny üstünlikli hasaplaň.
"X-Webhook-ID", "X-Signature".
Alyjydan 410 - retrany duruzmak (endpoint aýryldy).

13) Ýalňyşlyklary wersiýalaşdyrmak

'type '/' error _ code' - durnukly; täze - diňe goşmak.
Bedeniň shemasyny üýtgedeniňizde, API ýa-da 'problem + json-yň kiçi görnüşini ýokarlandyryň; v=2`.
Resminamalar: kodlar tablisasy + mysallar; Ýalňyşlyklar.

14) Resminamalar (OpenAPI bölekleri)

Global jogaplar

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 mysaly

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) Synag we hil

Şertnama-synaglar: 'application/problem + json', hökmany meýdanlar.
Negative tests: ähli şahalar 401/403/404/ 409/422/429/500.
Chaos/latency: 5xx/ 503/504/429 ('Retry-After').
Howpsuzlyk synaglary: içerki habarlaryň ýoklugy, dogry PII maskasy.
Backward-compat: Köne müşderiler täze meýdanlara düşünýärler (goşuň, bozmaň).

16) Girizmegiň çek-sanawy

• Ýeke 'problem + json' + durnukly 'error _ code'.
• HTTP/gRPC/GraphQL dogry semantika.
• Retriable/non-retriable + 'Retry-After '/arka-off teklipleri.
• Rate-limit sözbaşylary we 429 özüni alyp barşy.
• Idempotentlik ('Idempotency-Key', 409/412).
• Howpsuzlyk: stack traces/syr ýok, PII redaksiýasy.
• 'trace _ id '/' X-Request-ID' ähli ýalňyşlyklarda.
• Hata katalogynyň resminamalary we mysallar.
• Ýalňyşlyklaryň taksonomiýasy boýunça gözegçilik.
• Negatiw ssenariýalaryň awtotestleri.

17) Mini-FAQ

400 422-den nähili tapawutlanýar?
400 - bozulan haýyş (sintaksis/mazmunyň görnüşi). 422 - sintaksis boýunça dogry, ýöne işewürlik düzgünleri geçmedi.

Haçan 401, haçan 403?
401 - ýok/nädogry belgi; 403 - belgi bar, hukuklar ýeterlik däl.

Hemişe 'Retry-After' gerekmi?
429/503 üçin - hawa; galanlary üçin retriable - aç-açan maslahat bermek islenýär.

Jemi

Gowy dizaýn edilen ýalňyşlyklar - bu şertnama: dogry HTTP-status, bir 'problem + json', durnukly 'error _ code', retralar boýunça aýdyň maslahatlar we berk howpsuzlyk. Formaty standartlaşdyryň, taksonomiýany resminamalaşdyryň, telemetriýa we synaglary goşuň - API-leriňiz öňünden aýdyp boljak, howpsuz we integratorlara dostlukly bolar.