API Error Codes and Troubleshooting Guide

This article is created to guide you through API Error codes and how to troubleshoot them.

When your integration sends a request to the YellowCard Payment API, something can occasionally go wrong. That is completely normal during development and even in production. The key is knowing what each error means and what to do next.

Every error the API returns follows the same predictable structure: an HTTP status code, a machine-readable error code, and a plain-English message. Once you understand this pattern, debugging becomes straightforward.

Standard Error Response Format

Every error from the YellowCard API returns a JSON object with two fields: “code” (a machine-readable identifier) and “message” (a plain-English explanation). Always log both fields when handling errors in your integration.

Authentication Errors

Authentication errors occur before any transaction is processed. They mean the API could not verify who you are or what you are allowed to do. Fix these first; nothing else will work until authentication is resolved.

Error Code	HTTP Status	What It Means	What To Do
AuthenticationError	401	Your API key or request signature is invalid or missing.	Double-check your API key. Verify that your request signature is being generated correctly using the right secret. See the Authentication guide for the exact signing method.
PermissionError	403	Your API key does not have permission to access this endpoint.	Contact YellowCard to confirm which endpoints your API key is scoped for. You may need a key with elevated permissions for certain operations.

Note: API keys are environment-specific. A sandbox key will not work in production and vice versa. Always confirm you are using the correct Key for the environment you are targeting.

Request Validation Errors

These errors mean the API received your request but found a problem with the data you sent. The request never reached transaction processing. Review your request payload carefully before retrying.

Error Code	HTTP Status	What It Means	What To Do
PaymentValidationError	400	The request body is invalid. Required fields are missing, or KYC metadata is incomplete.	Check that all required fields are present in your payload. If full KYC is required for this transaction, make sure all KYC metadata fields are included.
InvalidRequestBody	400	An invalid body was sent to the Resolve Bank Account.	Review the request body structure against the API reference for the Resolve Bank Account endpoint. Ensure all fields are correctly formatted.
InvalidPhoneNumberFormat	400	The phone number is not in international format.	Format all phone numbers with the international dialling prefix (e.g +234 for Nigeria, +254 for Kenya). Do not use local formats like 0812 or 07XX
ResolveAccountError	400	The bank account number provided did not match any record at the selected bank.	Verify the account number and bank name with the recipient. Small typos in account numbers are the most common cause. Retry with the correct details.

Transaction Errors

Transaction errors occur after a payment or a receive request has been accepted but fails during or after processing. These errors may relate to the transaction state, expiry, or to a transaction not being found.

Error Code	HTTP Status	What It Means	What To Do
PaymentExpired	400	The payment request expired before it was approved or denied.	Create a new payment request. Make sure your customer acts promptly on payment instructions. Consider implementing a timeout warning in your user flow.
PaymentInvalidState	400	You attempted an operation on a payment that is in an incompatible state.	Check the current status of the payment before retrying. For example, you cannot approve a payment that has already been denied or completed.
PaymentNotFound	404	No payment exists with the ID provided.	Confirm the payment ID in your request. Check whether you are querying the correct environment (sandbox vs production). IDs do not carry over between environments.
CollectionNotFoundError	404	No receive transaction was found matching the provided details.	Verify the collection ID or reference you are querying. Ensure you are searching in the right environment.

Troubleshooting Best Practices

Following these practices will make your integration more resilient and reduce the time you spend debugging errors in production.

1. Always Check Transaction Status Before Retrying

For errors like GATEWAY_TIMEOUT and PROVIDER_ERROR, the transaction may have been processed on the provider's side even if you received an error. Always query the transaction status first before creating a new one. This prevents duplicate sends to the same recipient.

2. Use Sandbox Testing for All Error Scenarios

YellowCard's sandbox environment supports simulated error scenarios. Test your error handling logic thoroughly in the sandbox before going live. Refer to the Sandbox Testing guide for details on how to trigger specific error states.

3. Log Both the Code and Message Fields

Every error response contains both a machine-readable code and a human-readable message. Log both into your system. The code is what you use for programmatic error handling; the message is what helps your team understand what happened quickly.

4. Implement Exponential Backoff for Retries

For transient errors like GATEWAY_TIMEOUT, do not retry immediately. Implement exponential backoff — wait a short time, retry, wait longer, retry again — to avoid overwhelming the payment provider and to give the system time to recover.

5. Handle FRAUD_CHECK With Care

If a transaction returns a FRAUD_CHECK error, do not retry automatically. This error is triggered by YellowCard's Know Your Transaction (KYT) and transaction monitoring systems. Reach out to YellowCard support with the full transaction details for manual review.