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:

{
  "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; 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:

{
  "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, subscription renewals, domain registration, and VPS creation.
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.
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.	Back off and retry after the window resets.
500 Internal Server Error	Something failed on Hostinger's side.	Retry; if it persists, report it 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.

Handling errors in code

The SDKs raise an exception rather than returning an error value, carrying the status code and the response body. The CLI 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.

Calling the API directly, check the status code before parsing:

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