Errors

While the Flowbrite API is designed to be robust, errors can still occur on our side and yours. The information in this guide will help you understand and handle these errors effectively.

Error Responses

Errors will be returned for any request that generates a response in the 4xx or 5xx HTTP status code range.

The standard error response format is consistent across all endpoints. Each error response will consist of an error object that includes the following fields:

status: The HTTP status code of the response (will match the response status).
code: A string indicating the specific error code (e.g., "api.common.missingIdempotencyKey").
message: A human-readable message providing more details about the error.

Common Error Codes

You should expect to handle the following common errors for all API requests.

401 - Unauthorized

If your request is missing a valid API key or the key is invalid, you will receive a 401 Unauthorized response.

401 - Unauthorized

{
  "error": {
    "status": 401,
    "code": "api.common.unauthorized",
    "message": "You must be authenticated to access this endpoint."
  }
}

403 - Forbidden

If your API key does not have permission to access the requested resource, you will receive a 403 Forbidden response.

403 - Forbidden

{
  "error": {
    "status": 403,
    "code": "api.common.forbidden",
    "message": "You are missing the required permission: 'read:beneficiary' to access this endpoint."
  }
}

409 - Conflict

If you attempt to reuse an idempotency key within 15 minutes, you will receive a 409 Conflict response.

409 - Conflict

{
  "error": {
    "status": 409,
    "code": "api.common.reusedIdempotencyKey",
    "message": "The X-IDEMPOTENCY-KEY header value 'FLWBRT-01JXWKXK5E93TPC0HV2105T0ND' has already been used in the last 900 seconds"
  }
}

429 - Rate Limit Exceeded

If you attempt to make too many requests in a short period of time, you will receive a 429 Rate Limit Exceeded response.

429 - Rate Limit Exceeded

{
  "error": {
    "status": 429,
    "code": "api.common.rateLimitExceeded",
    "message": "Rate limit exceeded. Please retry in 60 seconds"
  }
}

400 - Bad Request (Validation Error)

If you provide invalid input or missing required fields, you will receive a 400 Bad Request response. In this instance the error object will also include a validationErrors array with details about the specific validation issues.

Each validation error will include:

property: The name of the field that failed validation.
message: A human-readable message describing the validation issue.
attemptedValue: The value that was provided for the field.

400 - Bad Request

{
  "error": {
    "status": 400,
    "code": "api.common.validationFailed",
    "message": "Validation failed",
    "validationErrors": [
      {
        "property": "walletId",
        "message": "Supplied ID is not valid for this type of resource. Expected 'wal_', but got 'bal_'",
        "attemptedValue": "bal_D01JTK7M2302PHR2GPKN0SRQYB1"
      }
    ]
  }
}

500 - Internal Server Error

We try really hard to make sure you don't encounter these errors, but sometimes they happen. If one does occur, you will receive a 500 Internal Server Error response.

500 - Internal Server Error

{
  "error": {
    "status": 500,
    "code": "api.common.internalServerError",
    "message": "An internal server error has occurred."
  }
}

503 - Service Unavailable

If you see this error, it means that the API is temporarily unavailable.

In this instance there will be no response body.

Correlation IDs

To help with debugging and support, each API request is assigned a unique correlation ID. This ID is included in the response headers and can be used to track the request in our server logs.

X-Correlation-Id: 01JXWNSZMS5N601QW8FE4QRBSF

If you encounter an error, please provide the correlation ID to our support team for assistance.