Skip to main content

Error Codes & Troubleshooting

HTTP error codes for the Fast Payments API

This guide explains the most common error responses returned by the Fast Payments API and provides recommended troubleshooting steps.

Fast Payments API uses standard HTTP status codes to indicate whether a request was successful or failed.

Error Codes

Fast Payments error codes
CodeDescriptionTypical Cause
400Bad RequestValidation error in the request payload
401UnauthorizedInvalid or expired access token
403ForbiddenIncorrect client permissions or token scope
422Duplicate Request ConflictReuse of an idempotency key with a modified payload
429Rate limit exceededToo many requests submitted in a short period
500Internal Server ErrorInternal or downstream processing failure
501Payment Initiation services not implemented for the requestUnsupported functionality or configuration
503Payment Initiation services unavailableService temporarily unavailable

Troubleshooting

400 — Bad Request

The request payload failed validation and could not be processed.

Common Causes

  • Missing required fields
  • Invalid payment details
  • Incorrect payload structure
  • Malformed JSON payload

How to Resolve

  • Validate request fields before submission
  • Confirm the payload matches the API specification
  • Ensure the request body contains valid JSON
  • Verify payment details are correctly formatted

401 — Unauthorized

The request could not be authenticated.

Common Causes

  • Missing OAuth access token
  • Expired access token
  • Invalid token
  • Incorrect Authorization header format

How to Resolve

  • Generate a new access token
  • Confirm the token is included in the request
  • Verify the token has not expired
  • Ensure the request uses a valid Bearer token

403 — Forbidden

The request was authenticated successfully, but the client is not authorized to access the resource.

Common Causes

  • Incorrect client configuration
  • Missing API scopes
  • Access not provisioned for the environment

How to Resolve

  • Verify your client configuration
  • Confirm the access token contains the required scopes
  • Ensure Fast Payments API access has been provisioned correctly

422 — Duplicate Request Conflict (Idempotency)

The request reused an existing idempotency key with a different payload.

Common Causes

  • Reusing an idempotency key across different payment requests
  • Modifying the request payload when retrying a payment request

How to Resolve

  • Ensure each unique payment request uses a unique idempotency key
  • Reuse the same request body when retrying with the same idempotency key
  • Generate a new idempotency key if the request payload changes

Store idempotency keys with the original request payload to ensure retries remain consistent.

429 — Too Many Requests

The request rate limit has been exceeded.

How to Resolve

  • Retry the request after a delay
  • Reduce request frequency during traffic spikes
  • Implement retry and exponential backoff handling for temporary failures such as 429, 500, and 503 responses

500 — Internal Server Error

An unexpected internal error occurred.

Common Causes

  • Internal processing failure
  • Downstream service issue
  • Temporary dependency outage

How to Resolve

  • Retry the request
  • Capture request details for troubleshooting
  • Contact support if the issue persists

501 — Not Implemented

The requested functionality is not supported for the request.

Common Causes

  • Unsupported payment flow
  • Feature not enabled for the environment
  • Invalid product or configuration setup

How to Resolve

  • Verify the API capability is supported
  • Confirm your environment and product configuration
  • Contact support if you believe the functionality should be available

503 — Service Unavailable

The service is temporarily unavailable.

Common Causes

  • Planned maintenance
  • Service outage
  • Downstream dependency unavailable

How to Resolve

  • Retry the request after a delay
  • Implement resilient retry handling
  • Monitor operational notifications from CommBank

Best Practices

  • Validate requests before submission
  • Refresh access tokens before expiry
  • Implement retry and backoff handling
  • Design applications to tolerate temporary failures
  • Use idempotency keys consistently when retrying payment requests

Key Considerations

  • 429, 500, and 503 errors may succeed when retried
  • 400, 401, 403, and 422 errors generally require request or configuration changes before retrying
  • Reusing an idempotency key with a modified request payload may result in a 422 response