Errors & Status Codes

The BlueRound API uses standard HTTP status codes to signal the outcome of every request. Whenever a request fails, the response body contains a structured error object that gives you a machine-readable code, a human-readable message, and a link to this page for further guidance.

---

---

Error Response Format

All error responses follow the same envelope schema:

Standard error envelope

{
  "error": {
    "code":    "RESOURCE_NOT_FOUND",
    "message": "User usr_00000 does not exist.",
    "docs":    "https://docs.blueround.com/api/errors#RESOURCE_NOT_FOUND",
    "details": []
  }
}

Error object fields

Field	Type	Description
code	string	Machine-readable error identifier. Use this in code, not message.
message	string	Human-readable explanation. Subject to change — do not parse.
docs	string	Permalink to the relevant section of this page.
details	array	Present on VALIDATION_ERROR only. Each item names a failing field.

For validation errors, details provides per-field information:

Validation error with field-level details

{
  "error": {
    "code":    "VALIDATION_ERROR",
    "message": "The request body contains invalid fields.",
    "docs":    "https://docs.blueround.com/api/errors#VALIDATION_ERROR",
    "details": [
      { "field": "email",  "issue": "Must be a valid email address." },
      { "field": "role",   "issue": "Must be one of: admin, member, viewer." }
    ]
  }
}

HTTP Status Code Reference

Code	Meaning	When it occurs
200	OK	Request succeeded. Response body contains data.
201	Created	Resource created successfully. Location header points to the new resource.
204	No Content	Request succeeded with no response body (e.g., token revocation).
400	Bad Request	Malformed JSON, invalid query parameter, or failed validation.
401	Unauthorized	Missing, expired, or malformed Bearer token.
403	Forbidden	Valid token but insufficient scope for this operation.
404	Not Found	Resource does not exist or is not visible to this token.
409	Conflict	Duplicate resource (e.g., email already registered).
422	Unprocessable Entity	Syntactically valid request, but semantically invalid (business rule violation).
429	Too Many Requests	Rate limit exceeded. Retry after Retry-After seconds.
500	Internal Server Error	Unexpected server-side failure. Retry with exponential back-off.
503	Service Unavailable	Temporary outage or maintenance. Check status.blueround.com.

Error Code Catalogue

VALIDATION_ERROR (400)

One or more request fields failed validation. Inspect the details array for per-field information and correct the request before retrying.

INVALID_TOKEN (401)

The supplied Bearer token is malformed or does not exist. Obtain a fresh token via OAuth 2.0 Authentication and retry.

TOKEN_EXPIRED (401)

The access token has passed its expires_in limit (3 600 seconds). Use the refresh token grant to obtain a new access token without re-authenticating the user.

Refresh an expired access token

curl -X POST "https://auth.blueround.com/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=def50200a9f3..." \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

INSUFFICIENT_SCOPE (403)

The token is valid but does not carry the scope required by this endpoint. Request a new token that includes the missing scope (e.g., users:write).

Scope requirements by endpoint

Endpoint	Required scope
GET /users	users:read
GET /users/{id}	users:read
POST /users	users:write
PATCH /users/{id}	users:write
DELETE /users/{id}	users:write

RESOURCE_NOT_FOUND (404)

The requested resource ID does not exist within your organization or is not accessible to the authenticated token. Verify the ID and that the resource belongs to your account.

DUPLICATE_RESOURCE (409)

A resource with a unique attribute (e.g., email address) already exists. Retrieve the existing resource instead of creating a new one, or use a different unique value.

RATE_LIMIT_EXCEEDED (429)

Your application has exceeded its allowed request rate. Inspect the Retry-After response header and pause requests for that many seconds before retrying.

Python — respecting Retry-After on 429 responses

import time
import requests

def get_with_retry(url, headers, max_retries=5):
    for attempt in range(max_retries):
        resp = requests.get(url, headers=headers)
        if resp.status_code == 429:
            wait = int(resp.headers.get("Retry-After", 5))
            print(f"Rate limited. Retrying in {wait}s…")
            time.sleep(wait)
            continue
        resp.raise_for_status()
        return resp.json()
    raise RuntimeError("Max retries exceeded.")

INTERNAL_ERROR (500)

An unexpected error occurred on the BlueRound servers. These are rare and typically transient. Retry using exponential back-off:

Recommended back-off schedule

Attempt	Wait before retry	Notes
1st retry	1 second	After the initial failure.
2nd retry	2 seconds	—
3rd retry	4 seconds	—
4th retry	8 seconds	—
Give up	—	Log the X-Request-ID and open a support ticket.

Important

Always log the X-Request-ID response header when a 500 error occurs. Include it in your support ticket so the BlueRound team can locate the server-side trace instantly.

Debugging Tips

Symptom	Likely cause and fix
401 on every request	Token missing from header, or Authorization: Bearer typo. Print the raw header your code sends.
401 after working for 1 hour	Access token expired. Implement automatic refresh — see TOKEN_EXPIRED (401).
403 with valid token	Token scope is too narrow. Re-request with the required scope listed in INSUFFICIENT_SCOPE (403).
404 for a resource you created	Check you are using the correct environment (production vs. staging). Staging data resets nightly.
Intermittent 500	Retry with back-off. If persistent, check status.blueround.com for an active incident.

See also

• About the BlueRound API — Rate limit headers and base URLs.

• OAuth 2.0 Authentication — Token acquisition, refresh, and revocation.

• Users — Status codes specific to the Users endpoints.