Errors
HTTP status codes and error response format for the HGV Traders API.
Error envelope
Failed requests return JSON with a single error string:
{ "error": "Invalid query" }Successful requests use the { "data": ... } envelope described in Overview.
Status codes
| Code | Meaning | Typical cause |
|---|---|---|
| 400 | Bad request | Invalid query parameters, malformed JSON body, or missing organisationId when the user belongs to multiple organisations |
| 401 | Unauthorized | Missing, invalid, expired, or revoked bearer token; invalid credentials on POST /api/v1/auth |
| 403 | Forbidden | PATCH /api/v1/accounts without ADMIN role on the target organisation |
| 404 | Not found | Resource does not exist, is not published, or the caller is not a member of the requested organisation |
| 429 | Too many requests | Rate limit exceeded — see Rate limits. Response includes a Retry-After header (seconds) |
| 503 | Service unavailable | Search backend temporarily unavailable on public list endpoints |
Rate limit responses
When rate limited, the response body is:
{ "error": "Too many requests. Please try again later." }or, for auth:
{ "error": "Too many attempts. Please try again later." }Always honour the Retry-After header before retrying.
Search errors
Public list endpoints (/api/v1/jobs, /events, /posts) may return:
- 400 with
"Invalid search query"— malformed free-text search syntax - 503 with
"Search unavailable"— search index temporarily unreachable
Retry 503 responses with exponential back-off.