Skip to main content

Error Codes & Troubleshooting

HTTP error codes for the NameCheck API

This guide explains the most common error responses returned by the NameCheck endpoint and provides recommended troubleshooting steps.

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

Error Codes

NameCheck error codes
CodeDescriptionTypical Cause
400Bad RequestValidation error in the request payload (incorrect BSB number, missing name, etc)
401UnauthorizedInvalid credentials or invalid access token
403ForbiddenIncorrect client ID or token scope
429Too Many RequestsRate limit exceeded (propagated from FDP rate limit)
500Internal Server ErrorDownstream processing failure
503Service UnavailableNameCheck service temporarily unavailable

Troubleshooting

400 — Bad Request

The request payload failed validation and could not be processed.

Common Causes

  • Invalid BSB format
  • Missing required fields
  • Invalid account details
  • Malformed JSON payload

How to Resolve

  • Validate request fields before submission
  • Ensure BSB and account number formats are correct
  • Confirm the payload matches the API specification
  • Check that the request body contains valid JSON

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 NameCheck API access has been provisioned correctly

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 while processing the request.

Common Causes

  • Downstream FDP platform issue
  • Internal processing failure
  • Temporary dependency outage

How to Resolve

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

503 — Service Unavailable

NameCheck 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 logic
  • Log request and response details
  • Design applications to tolerate temporary failures

Key Considerations

  • 429, 500, and 503 errors may succeed when retried
  • 400, 401, and 403 errors generally require request or configuration changes before retrying