API errors — bRRAIn Docs

How bRRAIn returns errors — RFC 7807 Problem Details, status codes, and common error types.

API errors

Every bRRAIn API returns errors in RFC 7807 Problem Details format. This page is the reference for what you'll see and how to handle it.

Format

HTTP/1.1 404 Not Found
Content-Type: application/problem+json

{
  "type": "https://docs.brrain.io/api-errors#record_not_found",
  "title": "Record not found",
  "status": 404,
  "detail": "No record with ID rec_45678 exists in the requested organization.",
  "instance": "/api/orgs/org_AB123/records/rec_45678",
  "request_id": "req_2c45a7f1b8c9..."
}

Fields:

  • type — a URL identifying the error kind. Always under docs.brrain.io/api-errors#.
  • title — short human description.
  • status — the HTTP status code (also in the response status line).
  • detail — what specifically went wrong this time.
  • instance — the path that generated the error.
  • request_id — useful when contacting support.

Errors may include extra fields for context (e.g., field when a validation error names the bad field).

Status code meanings

| Code | When | |---|---| | 400 Bad Request | Malformed input — bad JSON, missing required field, invalid enum. | | 401 Unauthorized | Missing or invalid authentication. | | 403 Forbidden | Authenticated but not allowed (role check, quota, policy). | | 404 Not Found | The resource doesn't exist or you can't see it. | | 409 Conflict | Concurrent modification or uniqueness violation. | | 422 Unprocessable Entity | Input is well-formed but semantically invalid. | | 429 Too Many Requests | Rate-limited. See Rate limits. | | 500 Internal Server Error | Bug on our side. Captured for investigation. | | 502 Bad Gateway | Upstream dependency unavailable. | | 503 Service Unavailable | Temporarily overloaded or undergoing maintenance. | | 504 Gateway Timeout | Upstream took too long. |

Common error types

  • unauthenticated — no credential.
  • invalid_token — token doesn't parse or is forged.
  • expired_token — token parsed but is past expiry.
  • revoked_token — token was explicitly revoked.
  • forbidden_role — your role doesn't allow this action.
  • forbidden_scope — the resource is outside your scope.
  • forbidden_policy — an organization policy forbids this action.
  • record_not_found
  • extension_not_installed
  • integration_not_configured
  • org_not_found
  • member_not_found
  • invalid_field — names the field in field.
  • missing_field — names the field.
  • invalid_enum_value — names the field and lists valid values.
  • body_too_large — payload exceeds the per-endpoint limit.
  • org_suspended — organization is in a suspended state.
  • pod_unavailable — your brain pod isn't reachable.
  • extension_unhealthy — the extension can't process requests right now.
  • quota_exceeded_storage
  • quota_exceeded_requests
  • quota_exceeded_compute
  • quota_exceeded_seats
  • concurrent_modification — the resource changed while you were modifying it. Refresh and retry.
  • uniqueness_violation — the value you're trying to set is already used (slug, email, etc.).
  • internal_error — captured; engineering will follow up via the request ID.
  • upstream_timeout — a dependency took too long.
  • upstream_unavailable — a dependency is down.

Handling errors

Idempotent retries

For 429 and 5xx errors, retry with exponential backoff. Use a backoff cap (commonly 5 attempts).

Non-retryable errors

For 4xx errors other than 429, do not retry without changing the request. The same request will fail the same way.

Validation errors

400 / 422 errors include a field and often a valid_values list. Use them to fix the request and resubmit.

Auth errors

401 means refresh or re-issue the credential. 403 is a permanent denial — your role / scope / policy needs to change before this request will succeed.

Logging the request_id

Capture the request_id in your application logs whenever you handle an API error. It's the fastest way for our support team to trace what happened on our side.

Where to next