Railmail używa konwencjonalnych kodów statusu HTTP do wskazania wyniku zapytania. Kody z zakresu 2xx oznaczają sukces, 4xx oznacza, że zapytanie się nie powiodło przy podanych danych, a 5xx oznacza błąd po stronie Railmail.
Wszystkie błędy używają RFC 7807 application/problem+json. Treść zawsze zawiera type, title i status, a może zawierać więcej pól:
{
"type": "https://api.railmail.app/problems/validation-error",
"title": "Validation failed",
"status": 400,
"detail": "One or more fields are invalid.",
"instance": "/api/v1/subscribers",
"timestamp": "2026-07-01T10:15:30Z",
"errors": {
"email": "must be a valid email address"
}
}
| Pole | Opis |
|---|
type | URI identyfikujące typ problemu. |
title | Krótkie, czytelne podsumowanie problemu. |
status | Kod statusu HTTP, powtórzony dla wygody. |
detail | Czytelne wyjaśnienie właściwe dla tego wystąpienia. |
instance | Odniesienie URI do konkretnego zapytania, które zawiodło. |
timestamp | Kiedy wystąpił błąd (ISO 8601). |
errors | Obecne przy błędach walidacji — mapa nazwy pola na komunikat. |
Najczęstsze kody statusu
| Status | Znaczenie | Co zrobić |
|---|
400 | Bad request | Popraw treść zapytania lub parametry. Sprawdź mapę errors dla szczegółów per pole. |
401 | Unauthorized | Brak lub nieważny klucz API. Zobacz Uwierzytelnianie. |
403 | Forbidden | Klucz jest ważny, ale nie ma zakresu wymaganego dla tej operacji. |
404 | Not found | Zasób nie istnieje w tym projekcie. |
409 | Conflict | Zapytanie koliduje z bieżącym stanem (np. duplikat). |
422 | Unprocessable | Zapytanie jest poprawne formalnie, ale niepoprawne semantycznie. |
429 | Too many requests | Osiągnięto limit zapytań. Zobacz Limity zapytań. |
5xx | Błąd serwera | Ponów z wykładniczym opóźnieniem. Jeśli się powtarza, skontaktuj się z pomocą. |
Zawsze czytaj pola title i detail — wyjaśniają, co poszło nie tak, znacznie lepiej niż sam kod statusu. Dla odpowiedzi 400 mapa errors wskazuje dokładnie, które pola poprawić.
