Errors and retries

Bridflow returns standard HTTP status codes with JSON error bodies. Integrations should separate user-correctable validation errors from transient conflicts and retryable upstream states.

Error body shape

Validation errors commonly use this shape:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "instance": "POST /saved-contacts/v1",
  "errors": {
    "message": [
      "We could not create this external bank account. Please review the bank account information and try again."
    ]
  },
  "traceId": "00-...",
  "requestId": "0H..."
}

Always log traceId and requestId. Show user-facing messages from errors.message when present.

Status code handling

Status	Meaning	Integration action
`400`	Request validation failed or selected route is unsupported.	Ask the user to correct input or refresh route discovery. Do not retry unchanged requests.
`401`	Missing or invalid authentication.	Refresh credentials or ask the operator to rotate the External API Consumer secret.
`403`	Authenticated identity cannot access the resource.	Stop and review account context or permissions.
`404`	Requested resource was not found for the current account.	Refresh local state; do not expose internal ids to users.
`409`	A resource already exists or is in a conflicting state.	Fetch current state, then update the existing resource or retry when marked retryable.
`429`	Rate limit reached.	Retry with backoff.
`5xx`	Server or upstream failure.	Retry with exponential backoff and alert if repeated.

Retry policy

Retry

Network timeouts.
429 responses after waiting.
5xx responses.
Explicit retryable conflict messages, including temporary resource-state conflicts.

Do not retry unchanged

Missing required fields.
Invalid account, bank, wallet, or route data.
Unsupported route combinations.
Duplicate Auto Convert Routes. Fetch the existing route and change its destination instead.

Idempotency

Use a stable idempotency key for create commands when the contract supports it. Persist the key with your local operation before sending the request. If the first attempt times out, retry with the same key instead of creating a new operation.

Do not generate a new idempotency key after a timeout unless you have confirmed the previous operation did not create a resource.

Common transfer errors

Scenario	Recommended handling
Unsupported source or destination route	Call `GetTransfersInfoQueryV1` again and only allow route objects returned by the API.
Missing dynamic field	Call `GetTransferRouteFieldMetadataQueryV1` for the selected route and rebuild the form from the returned fields.
Duplicate Auto Convert Route	Show the existing route and offer to change its destination.
Invalid saved contact details	Keep the user’s values in the form and ask them to review the specific field.
Temporary resource-state conflict	Retry with the same idempotency key after backoff, then fetch the resource state if the retry still fails.

Operational logging

For every failed call, store:

Endpoint and operation name.
Request id and trace id from the response.
Authenticated account or consumer id.
Idempotency key, when used.
Whether the request was a dry-run preview or an executed operation.