Error Handling
Our API uses conventional HTTP response codes to indicate success or failure of requests. This guide covers all error codes and how to handle them.
Error Response Format
All error responses follow a consistent JSON format:
{
"code": "invalid_consent",
"message": "Consent not found or has expired"
}Fields
| Field | Type | Description |
|---|---|---|
code | string | Machine-readable error code |
message | string | Human-readable error description |
HTTP Status Codes
2xx Success
| Code | Name | Description |
|---|---|---|
200 | OK | Request succeeded |
201 | Created | Resource created (payments, consents) |
204 | No Content | Request succeeded, no content to return |
4xx Client Errors
| Code | Name | Description |
|---|---|---|
400 | Bad Request | Invalid request format or parameters |
401 | Unauthorized | Missing or invalid authentication |
403 | Forbidden | Valid auth but insufficient permissions |
404 | Not Found | Resource does not exist |
405 | Method Not Allowed | HTTP method not supported for endpoint |
409 | Conflict | Request conflicts with current state |
422 | Unprocessable Entity | Request valid but cannot be processed |
429 | Too Many Requests | Rate limit exceeded |
5xx Server Errors
| Code | Name | Description |
|---|---|---|
500 | Internal Server Error | Unexpected server error |
502 | Bad Gateway | Upstream service unavailable |
503 | Service Unavailable | Service temporarily unavailable |
504 | Gateway Timeout | Upstream service timeout |
Error Codes Reference
Authentication Errors
Errors related to OAuth 2.0 and token handling.
| Error Code | HTTP | Description |
|---|---|---|
invalid_token | 401 | Access token is invalid, expired, or revoked |
invalid_client | 401 | Client authentication failed |
invalid_grant | 400 | Authorization grant is invalid or expired |
invalid_request | 400 | Request is missing required parameters |
unauthorized_client | 403 | Client not authorized for this grant type |
unsupported_grant_type | 400 | Grant type not supported |
invalid_scope | 400 | Requested scope is invalid or unknown |
Consent Errors
Errors related to consent management.
| Error Code | HTTP | Description |
|---|---|---|
missing_consent | 400 | X-Consent-ID header is required |
invalid_consent | 401 | Consent not found |
wrong_consent_type | 403 | Endpoint requires different consent type |
consent_invalid | 403 | Consent is not active or has expired |
consent_not_active | 403 | Consent has not been authorized by customer |
consent_expired | 403 | Consent has passed its expiration date |
consent_revoked | 403 | Consent was revoked by customer or TPP |
permission_denied | 403 | Consent does not include required permission |
Account Errors
Errors related to account access.
| Error Code | HTTP | Description |
|---|---|---|
account_not_found | 404 | Account does not exist |
account_not_consented | 403 | Account not covered by consent |
account_not_owned | 403 | Account not owned by authenticated customer |
account_locked | 403 | Account is locked and cannot be accessed |
Payment Errors
Errors related to payment initiation.
| Error Code | HTTP | Description |
|---|---|---|
payment_not_found | 404 | Payment does not exist |
invalid_amount | 400 | Amount format is invalid |
amount_exceeded | 400 | Amount exceeds scheme or account limits |
insufficient_funds | 422 | Insufficient funds for payment |
invalid_creditor | 400 | Creditor account details are invalid |
invalid_debtor | 400 | Debtor account details are invalid |
duplicate_payment | 409 | Payment with this instruction_id already exists |
payment_failed | 500 | Payment processing failed |
Funds Confirmation Errors
Errors related to funds confirmation.
| Error Code | HTTP | Description |
|---|---|---|
no_account | 400 | Consent does not specify an account |
balance_error | 500 | Failed to retrieve account balance |
Rate Limiting Errors
Errors related to rate limiting.
| Error Code | HTTP | Description |
|---|---|---|
rate_limit_exceeded | 429 | Too many requests, try again later |
quota_exceeded | 429 | Monthly API quota exceeded |
Troubleshooting Guide
Getting 401 Unauthorized
- Check that your access token is included in the Authorization header
- Verify the token has not expired (tokens last 5 minutes)
- Ensure you're using the correct token for the environment (sandbox vs production)
- For client credentials, verify your client_assertion JWT is correctly signed
Getting 403 Forbidden
- Verify the consent includes the required permissions
- Check that the consent status is 'authorized'
- For account endpoints, ensure the account is covered by the consent
- Confirm the consent has not expired
Getting 429 Too Many Requests
- Implement exponential backoff for retries
- Check the Retry-After header for when to retry
- Consider caching responses where appropriate
- Contact support if you need higher rate limits
Payment Stuck in 'pending'
- Some payments take longer to process (BACS: 3 days)
- Poll the payment status endpoint periodically
- Check for any error messages in the payment details
- For Faster Payments, status should update within minutes
Consent Authorization Failing
- Verify redirect_uris match exactly what was registered
- Check that state parameter is being correctly handled
- Ensure PKCE code_verifier matches the original code_challenge
- Review the error parameter in the callback URL
Retry Logic
Implement appropriate retry logic for transient errors:
| Status Code | Retry? | Strategy |
|---|---|---|
| 400-499 | No | Fix the request and try again |
| 429 | Yes | Wait for Retry-After duration |
| 500 | Maybe | Retry with exponential backoff (max 3 attempts) |
| 502, 503, 504 | Yes | Retry with exponential backoff |
Idempotency for Payments
Always use idempotency keys (instruction_id) when retrying payment requests to avoid duplicate payments.
Getting Help
If you're still experiencing issues after following this guide:
- Check our status page at status.hamsterbank.ai
- Review the API changelog for recent changes
- Search our developer forum for similar issues
- Contact developer support with your request_id for investigation