Error Codes & Troubleshooting

HTTP error codes for the PayTo API

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

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

Supported Endpoints

The following error codes may be returned by these PayTo endpoints:

POST /agreements
GET /agreements/{id}
PATCH /agreements/{id}
POST /agreements/validate
PATCH /agreements/{id}/status
POST /agreements/{id}/payments
GET /payments/{id}

Error Codes

PayTo error codes
Code	Description	Typical Cause
400	Bad Request	Invalid or malformed request payload
401	Unauthorized	Missing or invalid authentication token
403	Forbidden	Missing required authorization scope
404	Not Found	Requested agreement or payment resource does not exist
422	Unprocessable Entity	Business validation or semantic validation failure
500	Internal Server Error	Internal or downstream processing failure
503	Service Unavailable	Service temporarily unavailable

Troubleshooting

400 — Bad Request

The request payload is invalid or could not be processed.

Common Causes

Missing required fields
Incorrect payload structure
Invalid field formats
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 field values 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 perform the operation.

Common Causes

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

How to Resolve

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

404 — Not Found

The requested resource could not be found.

Common Causes

Invalid agreement ID
Invalid payment ID
Resource does not exist
Resource is unavailable in the current environment

How to Resolve

Verify the resource identifier is correct
Confirm the resource exists in the target environment
Ensure the request is using the correct endpoint and identifiers

422 — Unprocessable Entity

The request was received successfully but failed business or semantic validation.

Common Causes

Invalid agreement state transition
Business rule validation failure
Invalid payment or agreement status
Request action not permitted for the current resource state

How to Resolve

Review the request payload and business rules
Confirm the requested operation is valid for the current resource state
Verify all mandatory business conditions have been met before retrying

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

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

Health Endpoint

The /health endpoint returns the following status codes.

PayTo health endpoint status codes
Code	Description
500	Internal Server Error — An internal server error has occurred.

A 500 response from the health endpoint may indicate the service or a downstream dependency is unavailable.

Best Practices

Validate requests before submission
Refresh access tokens before expiry
Implement retry and backoff handling
Design applications to tolerate temporary failures
Verify resource identifiers before making requests

Key Considerations

500 and 503 errors may succeed when retried
400, 401, 403, 404, and 422 errors generally require request or configuration changes before retrying
422 responses are typically caused by business validation or invalid resource state transitions