Skip to content
/
Response Codes and Errors
Last updated

Response Codes and Errors

The Bermuda Commercial Bank RESTful Open Banking API uses standard HTTP status codes to indicate the result of API requests. This section outlines the most common response codes and includes examples of potential error messages.

✅ Success Responses

200 OK

The request was successful and a valid response object is returned.

Example:

{
  "id": "12345",
  "status": "COMPLETED",
  "data": {
    "accountNumber": "1000078766",
    "balance": "1000.00"
  }
}

202 Accepted

The request was accepted for asynchronous processing. This is expected for background-job workflows such as virtual account creation.

Example:

{
  "jobId": "550e8400-e29b-41d4-a716-446655440001",
  "status": "Pending",
  "statusUrl": "https://api.bcb.bm/v1/jobs/550e8400-e29b-41d4-a716-446655440001",
  "resultUrl": "https://api.bcb.bm/v1/jobs/550e8400-e29b-41d4-a716-446655440001/results"
}

⚠️ Client Errors

400 Bad Request

The request is malformed or contains invalid parameters.

Example:

"Invalid request parameters"

Virtual Accounts examples:

  • creating a virtual account in a currency that has not been provisioned for your client
  • attempting a VAS flow that is not allowed, such as virtual account to virtual account transfer

401 Unauthorized

Authentication is missing or invalid.

Example:

"Authentication failed"

403 Forbidden

Access is denied—typically due to IP restrictions or insufficient permissions.

Example:

"IP address not allowed"

404 Not Found

The requested resource could not be found. Ensure the endpoint and identifiers are correct.

Example:

"Account not found"

409 Conflict

The request could not be completed due to a conflict with the current state of the resource.

Example:

"Conflict detected"

429 Too Many Requests

You’ve exceeded the allowed request quota. Wait until the rate limit resets before trying again.

Example:

{
  "error": "Rate limit exceeded",
  "message": "You have exceeded the 300 requests per 60 minutes limit. Please wait for the rate limit to reset.",
  "retry_after": "60 minute(s)"
}

❌ Server Errors

500 Internal Server Error

An unexpected error occurred on the server. Try again later or contact support.

Example:

"An unknown error occurred"

🛠️ Best Practices

  • Always validate inputs before making API requests.
  • Implement error handling for each status code.
  • Use the retry_after value to manage rate limit retries.
  • For Virtual Accounts background jobs, always inspect GET /v1/jobs/{jobId} and GET /v1/jobs/{jobId}/results rather than relying on the initial 202 alone.
  • For VAS-specific failure patterns, read the Virtual Accounts Troubleshooting guide.
  • Contact support for persistent issues at 📧 api@bcb.bm.
Previous page
Next page