The Bardge API uses conventional HTTP status codes to indicate whether a request succeeded or failed. Every error — no exceptions — returns a structured JSON object with a fixed shape.Error object#
{
"error": {
"type": "invalid_request_error",
"code": "pass_not_found",
"message": "No pass exists with id pass_01H8XYZ.",
"request_id": "req_01H8XYZABCDE"
}
}
| Field | Description |
|---|
type | Broad error category — one of the fixed types below |
code | Machine-readable error code — branch your logic on this |
message | Human-readable description |
request_id | Unique ID for this request — include in support tickets |
HTTP status codes#
| Code | Meaning |
|---|
200 | Success |
201 | Resource created |
400 | Invalid request — bad or missing input |
401 | Authentication error — missing or invalid API key |
403 | Permission error — valid key, not authorised for this resource |
404 | Resource not found |
409 | Conflict — state or idempotency conflict |
500 | Server error |
Error types#
| Type | When |
|---|
invalid_request_error | Malformed or missing input (400) |
authentication_error | Missing or invalid API key (401) |
permission_error | Valid key, not authorised for this resource (403) |
api_error | Server-side bug (500) |
idempotency_error | Idempotency key reused with a different request body (409) |
resource_conflict_error | State conflict — slot unavailable, class full, already cancelled (409) |
Common error codes#
| Code | Status | Description |
|---|
validation_error | 400 | A required field is missing or a field value is invalid |
invalid_api_key | 401 | The API key provided is invalid |
account_disabled | 403 | Your reseller account has been disabled |
resource_not_found | 404 | The requested resource does not exist |
idempotency_key_reused | 409 | An idempotency key was reused with a different request body |
slot_unavailable | 409 | The requested booking slot is no longer available |
class_full | 409 | The class has reached its maximum capacity |
already_cancelled | 409 | The booking has already been cancelled |
internal_server_error | 500 | An unexpected error occurred on our side |
Handling errors#
Branch on error.code, not error.type. New codes are added over time — that is not a breaking change.
Surface error.message to end users only for invalid_request_error. For all other types, show a generic message.
Always log error.request_id — it is required for support escalation.
Modified at 2026-05-19 11:14:16
