Railmail uses conventional HTTP status codes to indicate the outcome of a request. Codes in the 2xx range mean success, 4xx means the request failed given the information provided, and 5xx means something went wrong on Railmail’s side.
All errors use RFC 7807 application/problem+json. The body always includes type, title and status, and may include more:
{
"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"
}
}
| Field | Description |
|---|
type | A URI identifying the problem type. |
title | A short, human-readable summary of the problem. |
status | The HTTP status code, repeated for convenience. |
detail | A human-readable explanation specific to this occurrence. |
instance | A URI reference for the specific request that failed. |
timestamp | When the error occurred (ISO 8601). |
errors | Present on validation failures — a map of field name to message. |
Common status codes
| Status | Meaning | What to do |
|---|
400 | Bad request | Fix the request body or parameters. Check the errors map for field-level detail. |
401 | Unauthorized | The API key is missing or invalid. See Authentication. |
403 | Forbidden | The key is valid but lacks the required scope for this operation. |
404 | Not found | The resource doesn’t exist in this project. |
409 | Conflict | The request conflicts with the current state (for example, a duplicate). |
422 | Unprocessable | The request is well-formed but semantically invalid. |
429 | Too many requests | You’ve hit the rate limit. See Rate limits. |
5xx | Server error | Retry with backoff. If it persists, contact support. |
Always read the title and detail fields — they explain what went wrong far better than the status code alone. For 400 responses, the errors map pinpoints exactly which fields to fix.
