Errors & status codes

The Grand Public API uses conventional HTTP status codes to signal success and failure. A 2xx means your request worked; a 4xx means something about the request needs fixing; a 5xx means something went wrong on our side.

Error response shape

When a request fails, the response body is JSON containing a human-readable message describing what went wrong:

{
  "message": "Unknown jurisdiction: XX"
}

Always branch on the HTTP status code first, then use message for logging and debugging. Don't pattern-match on the exact wording of message — it may change.

Status codes

Status	Meaning	What to do
`200 OK`	The request succeeded.	Process the response body.
`400 Bad Request`	A parameter is missing or invalid — e.g. an empty `q`, a `pageSize` outside 1–50, or an unrecognised `jurisdiction`.	Fix the request. The `message` says which parameter is wrong.
`401 Unauthorized`	Missing, malformed, or expired token — or invalid client credentials on the token endpoint.	Re-authenticate. See Authentication.
`404 Not Found`	No company matches the given registration number and jurisdiction (`/v1/profile` only).	Verify the `companyNumber` and `jurisdiction`. Use search to confirm the number.
`429 Too Many Requests`	You've exceeded your request quota.	Back off and retry. See Rate limits.
`5xx Server Error`	An unexpected error on Grand's side.	Retry with backoff. If it persists, contact support.

Common errors and how to fix them

Scenario	Status	Cause & fix
Empty or missing `q` on search	`400`	`q` is required. Provide a non-blank company name.
`pageSize` of 0 or 51+	`400`	`pageSize` must be between 1 and 50.
Unknown jurisdiction code	`400`	Use a supported jurisdiction — `GB` or `IE`.
No `Authorization` header	`401`	Send `Authorization: Bearer <token>`.
Expired token	`401`	Request a new token — they last one hour.
Bad client credentials	`401`	Check your `client_id` / `client_secret`.
Profile lookup for a number that doesn't exist	`404`	Confirm the company number via search first.

Examples

400 — unknown jurisdiction

curl -s -o /dev/null -w "%{http_code}\n" \
  -H "Authorization: Bearer $TOKEN" \
  "https://public-api.heygrand.com/v1/search?q=Acme&jurisdiction=ZZ"
# 400

{ "message": "Unknown jurisdiction: ZZ" }

401 — missing token

curl -s -o /dev/null -w "%{http_code}\n" \
  "https://public-api.heygrand.com/v1/profile/12345678?jurisdiction=GB"
# 401

404 — company not found

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://public-api.heygrand.com/v1/profile/00000000?jurisdiction=GB"

{ "message": "Company not found" }

Build retries with exponential backoff for 429 and 5xx responses, but not for 400, 401, or 404 — those won't succeed on retry without changing the request.

Jurisdictions