Developer · FREE

Kontrakt błędów HTTP

Ujednolica jak API mówi o porażce: jeden kształt ciała błędu, mapa wyjątków na kody, co idzie do logu a co do klienta. Kończy spór 'w 200 wrzucamy {ok:false}'.

reviewed:

Jak zainstalować

  1. Uzupełnij pola poniżej (albo zostaw nazwy zmiennych i dopisz w czacie). Wartości z Skill creatora na liście podstawiają się same.
  2. Kopiuj, potem wklej w Claude.ai (instrukcje projektu) albo ChatGPT (Custom Instructions).
  3. Albo pobierz SKILL.md i połóż w folderze skilli Claude Code.
SKILL
Istniejące odpowiedzi błędów (wklejka JSON / lista): [BLEDY]. Stack: [STACK]. Czy jest korelacja request-id: [KORELACJA].

NIE PISZ HANDLERÓW BIZNESOWYCH. To nie jest ADR (adr-krotki wybiera kształt raz; tu spisujesz mapę wyjątków na ten kształt). Jeśli nie ma jeszcze endpointu - odeślij do spec-kontraktu-api i stop.
Jeśli [BLEDY] puste - poproś o 3 prawdziwe odpowiedzi (albo logi statusów) i stop.

Zwracasz:

## 1. Jeden kształt ciała
Wybierz RFC 7807 (`type`, `title`, `status`, `detail`, `instance`) ALBO istniejący kształt z [BLEDY], jeśli już jest jeden. Nie mieszaj. Dopisz `request_id` (albo pokaż, że [KORELACJA] go daje).

Jeden przykład JSON (bez sekretów, bez stacku):

```json
{
  "type": "https://api.example.com/errors/order-not-found",
  "title": "Order not found",
  "status": 404,
  "detail": "Order 1832 does not exist.",
  "instance": "/orders/1832",
  "code": "order.not_found",
  "request_id": "req_..."
}
```

Zakaz: `200` + `{ "ok": false }`. Porażka = kod 4xx/5xx.

## 2. Mapa wyjątków
Tabela: wyjątek / warunek | status | kod maszynowy | ciało (które pola) | logować stack? | alert?

Twarde mapowanie (nie negocjuj bez ADR):

- walidacja wejścia = 422
- brak zasobu = 404
- spór stanu / duplikat mutacji = 409
- brak albo zły auth = 401
- brak uprawnienia = 403
- timeout zależności = 504
- nieobsłużony błąd serwera = 500 (i to JEDYNE miejsce na 500 z tej listy)

## 3. Log vs klient
- klient: status, `code`, `title`/`detail` bez wycieku, `request_id`
- log: `request_id`, wyjątek, stack, dane potrzebne do debug (bez haseł, tokenów, PESEL, kart)
- sekrety i stack trace NIGDY w ciele odpowiedzi
- `request_id` ZAWSZE w odpowiedzi; jeśli [KORELACJA] = nie - dopisz "brak, dodać middleware" jako BLOKUJĄCE

Na końcu: lista istniejących odpowiedzi z [BLEDY], które łamią kontrakt (status + pole). Zero "przy okazji nowy logger". Dywiz "-". JSON po angielsku.

Zanim wkleisz

Skill vs zły prompt

Zły prompt

Zwracaj błędy w 200 z ok false, żeby frontendowi było łatwiej, best practices.

Skill

Istniejące odpowiedzi błędów (wklejka JSON / lista): [BLEDY]. Stack: [STACK]. Czy jest korelacja request-id: [KORELACJA].

NIE PISZ HANDLERÓW BIZNESOWYCH. To nie jest ADR (adr-krotki wybiera kształt raz; tu spisujesz mapę wyjątków na ten kształt). Jeśli nie ma jeszcze endpointu - odeślij do spec-kontraktu-api i stop.
Jeśli [BLEDY] puste - poproś o 3 prawdziwe odpowiedzi (albo logi statusów) i stop.

Zwracasz:

## 1. Jeden kształt ciała

Użyj z tym narzędziem

Lekcja: claude-start-06-claude-dla-programisty

Pytania

Jak użyć skilla "Kontrakt błędów HTTP" w Claude?

Uzupełnij pola w nawiasach (albo weź je z profilu Skill creator na /skille), kliknij Kopiuj i wklej treść do instrukcji projektu w Claude.ai. W Claude Code kliknij Pobierz SKILL.md i połóż plik w folderze skilli. Skill działa też w ChatGPT (Custom Instructions). Nie chowa się za paywallem: kopia jest darmowa.

Kiedy tego skilla NIE używać?

Nie gdy to skrypt CLI bez HTTP. Nie do ukrywania 500 przed monitoringiem. Nie gdy nie masz jeszcze żadnego endpointu (najpierw spec-kontraktu-api).