Error Responses

Bridge returns structured error responses for failed requests.

Error Response Structure

When an error occurs, Bridge returns a consistent JSON object:

1
{
2
  "type": "resource_error",
3
  "requestId": "req_abc123"
4
}

Response Fields

Field Errors

For validation failures (HTTP 400 or 422), Bridge may include fields:

1
{
2
  "type": "validation_error",
3
  "fields": [
4
    {
5
      "field": "email",
6
      "type": "required"
7
    },
8
    {
9
      "field": "password",
10
      "type": "min",
11
      "value": "short"
12
    }
13
  ],
14
  "requestId": "req_abc123"
15
}

Field Error Structure

Nested Field Errors

field uses dot notation for nested objects:

1
{
2
  "type": "validation_error",
3
  "fields": [
4
    {
5
      "field": "address.street",
6
      "type": "required"
7
    },
8
    {
9
      "field": "address.zipCode",
10
      "type": "length",
11
      "value": "123"
12
    }
13
  ]
14
}

HTTP Status Codes

Bridge uses conventional HTTP status codes:

Error Types

The type field is the primary way to classify errors.

invalid_request_error

The request has invalid parameters. Check fields and param when present.

1
{
2
  "type": "invalid_request_error",
3
  "param": "dateOfBirth",
4
  "requestId": "req_abc123"
5
}

authentication_error

Authentication failed.

1
{
2
  "type": "authentication_error",
3
  "requestId": "req_abc123"
4
}

permission_error

Authenticated caller lacks permission for this resource.

1
{
2
  "type": "permission_error",
3
  "requestId": "req_abc123"
4
}

resource_error

Requested resource could not be found.

1
{
2
  "type": "resource_error",
3
  "requestId": "req_abc123"
4
}

conflict_error

Request conflicts with the current resource state.

1
{
2
  "type": "conflict_error",
3
  "requestId": "req_abc123"
4
}

validation_error

Request failed validation rules.

1
{
2
  "type": "validation_error",
3
  "param": "dateOfBirth",
4
  "requestId": "req_abc123"
5
}

rate_limit_error

Rate limit was exceeded.

1
{
2
  "type": "rate_limit_error",
3
  "requestId": "req_abc123"
4
}

api_error

Generic server-side error.

1
{
2
  "type": "api_error",
3
  "requestId": "req_abc123"
4
}

Handling Errors

Best Practices

1. Check HTTP status code first for broad request outcome.
2. Use type for client branching (primary discriminator).
3. Use fields for form validation UX when present.
4. Log the requestId and include it in support requests.

Example Error Handling (TypeScript)

1
import { BridgeAPI } from "@usebridge/api"
2
3
try {
4
  const patient = await bridge.patients.get({ id: "pat_abc123" })
5
} catch (error) {
6
  if (error.type === "resource_error") {
7
    // Handle not found
8
  } else if (error.type === "validation_error") {
9
    error.fields?.forEach((field) => {
10
      // Map field errors to form UI
11
    })
12
  } else if (error.type === "rate_limit_error") {
13
    // Retry with backoff
14
  }
15
16
  const requestId = error.requestId
17
}

Retryable Errors

Usually retryable:

• 500 Internal Server Error
• 429 Too Many Requests

Usually non-retryable without input/auth changes:

• 400, 401, 403, 404, 422

Request IDs

Error responses may include requestId. Successful responses expose request IDs in the X-Request-ID header.

When contacting Bridge support, include the request ID.

You can provide your own request ID header:

1
X-Request-ID: my-custom-id-123