The Better Regulation API uses standard HTTP status codes to indicate whether a request succeeded or failed. Errors are returned as JSON in the response body, giving you the information needed to diagnose and handle them programmatically.
Error response format
All error responses follow a consistent JSON structure. The fields returned may vary depending on the error type, but the format is always the same.
{
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2",
"title": "A human-readable description of the error.",
"status": 400,
"detail": "Additional detail about what went wrong."
}Response fields
| Field | Type | Description |
|---|---|---|
type |
String | A URL referencing the relevant section of the HTTP specification for this status code. |
title |
String | A human-readable summary of the error. |
status |
Integer | The HTTP status code. |
detail |
String | Additional context about the error. Not always present. |
HTTP status codes
The following status codes may be returned by the API.
| Code | Status | Description |
|---|---|---|
200 |
OK | The request was successful. A response body is returned. |
400 |
Bad Request | The request could not be understood. This typically means a parameter is missing, misnamed, or formatted incorrectly. |
401 |
Unauthorized | No valid API key was provided. Check that your access_token is included and correctly formed. |
403 |
Forbidden | Your API key is valid but does not have permission to access the requested resource. |
404 |
Not Found | The requested document or resource does not exist. Check that the ID is correct. |
500 |
Internal Server Error | An unexpected error occurred on the server. If this persists, contact support. |
Example responses
401 Unauthorised
Returned when the access_token parameter is missing or the key is not recognised.
{
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2",
"title": "Bad credentials. Anonymous user resolved for a resource that requires authentication.",
"status": 401,
"detail": "Unauthorized"
}400 Bad Request
Returned when one or more request parameters are missing or incorrectly formatted.
{
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2",
"title": "Badly formed parameters",
"status": 400
}Recommendations
When integrating with the API, we recommend handling errors explicitly in your code rather than assuming requests will always succeed.
Check the
status field first. Use the integer value in the response body to drive your error handling logic — it will always be