Error Handling

Error response format

{
  "detail": "Human-readable error message"
}

For server errors (500), the response includes additional fields:

{
  "error": "internal_server_error",
  "detail": "An unexpected error occurred",
  "status_code": 500,
  "request_id": "abc123-def456-..."
}

The request_id can be provided to support for troubleshooting.

HTTP status codes

Status	Meaning	When it occurs
200	Success	Request processed successfully
400	Bad Request	Invalid request body, missing required fields, invalid values
401	Unauthorized	Missing, invalid, or expired API credentials
403	Forbidden	Valid credentials but access denied (e.g. suspended organisation)
404	Not Found	Award code not found, batch not found, or endpoint does not exist
429	Too Many Requests	Rate limit exceeded — see Rate Limiting
500	Internal Server Error	Unexpected server error

Common 400 errors

Missing required field

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "award_code"],
      "msg": "Field required"
    }
  ]
}

Invalid award code

{
  "detail": "Award MA000999 is not available for deterministic calculations"
}

Invalid classification

{
  "detail": "Classification INVALID not found for award MA000009"
}

Invalid employment type

{
  "detail": "Invalid employment_type. Must be one of: full_time, part_time, casual"
}

Handling errors in code

response = requests.post(url, headers=headers, json=payload)

if response.status_code == 200:
    result = response.json()
elif response.status_code == 400:
    error = response.json()
    print(f"Bad request: {error['detail']}")
elif response.status_code == 401:
    print("Check your API credentials")
elif response.status_code == 404:
    print("Award or resource not found")
elif response.status_code == 429:
    retry_after = int(response.headers.get("Retry-After", 5))
    time.sleep(retry_after)
else:
    print(f"Unexpected error {response.status_code}: {response.text}")

Request tracing

All responses include an X-Request-ID header. Include this ID when contacting support about a specific request:

X-Request-ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890