> For the complete documentation index, see [llms.txt](https://docs.hostinger.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hostinger.com/api-reference/errors.md). # Errors What a failed Hostinger API request looks like — the error response shape, validation errors, the full list of status codes, and how to use the correlation ID when reporting a problem. The Hostinger API uses standard HTTP status codes. Anything in the `2xx` range succeeded; `4xx` means the request was rejected and `5xx` means something failed on Hostinger's side. Every error response is JSON, regardless of the status code. ## Error response shape A failed request returns a `message` and a `correlation_id`: ```json { "message": "Unauthenticated.", "correlation_id": "26a91bd9-f8c8-4a83-9df9-83e23d696fe3" } ``` * **`message`** — a human-readable description of what went wrong. It's meant for a developer reading a log, not for display to your end users. * **`correlation_id`** — a unique ID for this request. Quote it when you [report a problem](/api-reference/support.md); it's how support finds the request in Hostinger's logs. The same ID is also returned as an `x-correlation-id` response header, so you can capture it even when you don't parse the body. ## Validation errors A `422 Unprocessable Content` means the request was well-formed but the values didn't pass validation. These responses add an `errors` object keyed by field name, where each value is a list of everything wrong with that field: ```json { "message": "The name field is required. (and 1 more error)", "errors": { "name": [ "The name field is required." ], "port": [ "The port must be a number." ] }, "correlation_id": "26a91bd9-f8c8-4a83-9df9-83e23d696fe3" } ``` `message` is a summary of the first problem. Read `errors` when you need to attribute failures to specific fields — for example to highlight inputs in a form. ## Status codes | Code | Meaning | What to do | | --------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `200 OK` | The request succeeded. | — | | `201 Created` | A resource was created. | Read the new resource from the response body. | | `202 Accepted` | A payment is being processed and the order will complete asynchronously. | Poll the relevant resource until it appears. Returned by the purchase endpoints for [billing orders](/api-reference/endpoints/billing/orders/create-purchase-order.md), [subscription renewals](/api-reference/endpoints/billing/subscriptions/renew-subscription.md), [domain registration](/api-reference/endpoints/domains/portfolio/purchase-new-domain.md), and [VPS creation](/api-reference/endpoints/vps/virtual-machine/purchase-new-virtual-machine.md). | | `400 Bad Request` | The request couldn't be processed as sent. | Check the `message`; fix the request. | | `401 Unauthorized` | The token is missing, malformed, expired, or revoked. | Check the `Authorization` header and the token's status in [hPanel → API](https://hpanel.hostinger.com/profile/api). | | `404 Not Found` | The route doesn't exist, or the resource doesn't exist on your account. | Verify the path and any IDs in it. | | `409 Conflict` | The resource is in a state that doesn't allow this operation, or it already exists. | Read the `message` — it names the conflict. | | `422 Unprocessable Content` | Validation failed. | Read the `errors` object. | | `429 Too Many Requests` | You exceeded the [rate limit](/api-reference/overview.md#rate-limits). | Back off and retry after the window resets. | | `500 Internal Server Error` | Something failed on Hostinger's side. | Retry; if it persists, [report it](/api-reference/support.md) with the correlation ID. | | `502 Bad Gateway` | An upstream service was unreachable. | Retry with backoff. | > The API doesn't use `403`. A permission problem surfaces as `401` if the token itself is rejected, or as `404` if the token is valid but the resource isn't visible to the user who owns it. Tokens inherit the permissions of the user who created them — see [Security & Access](/account/security.md). ## Handling errors in code The [SDKs](/api-reference/sdks.md) raise an exception rather than returning an error value, carrying the status code and the response body. The [CLI](/api-reference/cli.md) exits `1` and prints the raw response body, so you can parse the same `message` and `correlation_id` out of it — see [Scripting with the CLI](/api-reference/cli-scripting.md). Calling the API directly, check the status code before parsing: ```bash response=$(curl -s -w '\n%{http_code}' https://developers.hostinger.com/api/hosting/v1/websites \ -H "Authorization: Bearer $HOSTINGER_API_TOKEN") status=$(echo "$response" | tail -n1) body=$(echo "$response" | sed '$d') if [ "$status" -ge 400 ]; then echo "Request failed ($status): $(echo "$body" | jq -r '.message')" >&2 echo "Correlation ID: $(echo "$body" | jq -r '.correlation_id')" >&2 exit 1 fi ``` ## Retrying Retry `429`, `500`, and `502` — they're transient. Don't retry `400`, `401`, `404`, `409`, or `422`; the same request will fail the same way. Use exponential backoff rather than a fixed delay, and cap the number of attempts. Repeatedly hammering the API after a `429` can get your IP temporarily blocked. Retrying a `POST` is only safe when you know the first attempt didn't take effect. Where a `202` was returned, the operation is already in flight — poll for the result instead of sending the request again. *** *Last updated: September 10, 2026*