Skip to main content
When a request fails, the Thiqwave API returns a JSON response body with a consistent structure alongside an appropriate HTTP status code. Your application should always inspect both the status code and the response body to determine the correct recovery path.

​
Error Response Format

Every error response includes three fields:
FieldTypeDescription
errorstringA short, machine-readable error identifier
messagestringA human-readable description of what went wrong
codestringAn application-level code for precise error handling
{
  "error": "Unauthorized",
  "message": "The API key provided is invalid or has been revoked.",
  "code": "INVALID_API_KEY"
}

​
HTTP Status Codes

The request was malformed or contained invalid parameters. Check that all required fields are present and that values conform to the expected types and formats documented in the API reference.Common causes:
  • Missing required fields in the request body
  • Incorrect data types (e.g. passing a string where a number is expected)
  • Malformed JSON body
Your request did not include a valid API key, or the key has been revoked. Ensure you are passing your key in the X-API-Key header on every request.Common causes:
  • Missing X-API-Key header
  • Using a key that has been deleted or expired
  • Using a staging key against the production endpoint, or vice versa
Your API key is valid but does not have permission to perform the requested action. This usually means the operation is outside the scope granted to your API key.Common causes:
  • Attempting to access a resource that belongs to a different partner
  • Accessing a feature that has not been enabled for your account
The resource you requested does not exist. Verify that the ID or path you are using is correct and that the resource has not been deleted.Common causes:
  • Typo in a resource ID
  • The resource was previously deleted
  • Using an ID from a different environment (e.g. a staging ID against production)
The request conflicts with the current state of the server. This is most commonly returned when an idempotency key is reused with a different request body, or when you attempt to create a resource that already exists.Common causes:
  • Reusing an Idempotency-Key with a different payload
  • Attempting to create a duplicate resource
See the Idempotency guide for details on how to handle key conflicts.
The request body was syntactically valid JSON but failed business-logic validation. The message field will describe which field or rule triggered the failure.Common causes:
  • A field value falls outside an accepted range
  • A required relationship (e.g. a business account) has not been fully onboarded
  • A compliance check is pending before the operation can proceed
You have exceeded the rate limit for your API key. The response will include a Retry-After header indicating how many seconds you should wait before retrying.See Rate Limits for current limits and guidance on handling this response.
An unexpected error occurred on Thiqwave’s servers. These are rare. If you receive a 500 consistently for the same request, contact support with the full request details and the timestamp of the failure.You can safely retry 500 responses with exponential backoff.

​
Application Error Codes

The code field in the error body provides a more specific identifier that you can use in your error-handling logic.
HTTP status: 401The API key in the X-API-Key header is missing, malformed, or has been revoked. Retrieve a valid key from the Thiqwave Dashboard under Settings → API Keys.
HTTP status: 429Your integration has sent more requests than allowed within the current time window. Wait for the duration specified in the Retry-After response header before retrying, and consider implementing exponential backoff.
HTTP status: 422One or more fields in the request body failed validation. The message field will identify the specific field and the rule that was violated. Correct the value and resubmit the request.
HTTP status: 404The requested resource does not exist. Check that the resource ID in the path is correct and that you are targeting the right environment.
HTTP status: 403The operation cannot proceed because a required compliance step has not been completed. This is typically KYB (Know Your Business) verification. Complete onboarding in the dashboard before retrying.
HTTP status: 422The transaction could not be processed. This may be due to insufficient funds, a rejected payment rail, or a compliance hold. The message field will provide additional context. Do not automatically retry failed transactions without investigating the cause first.
HTTP status: 403Your API key does not have the permissions required to perform this action. This is distinct from COMPLIANCE_REQUIRED — the key itself is valid, but its scope does not cover the requested operation. Review the key’s permissions in the dashboard or contact your account manager.

​
Example Error Response

The following is a full example of an error response you might receive when submitting a transaction before KYB verification is complete: 
{
  "error": "Forbidden",
  "message": "Your business account must complete KYB verification before initiating transactions.",
  "code": "COMPLIANCE_REQUIRED"
}

​
Troubleshooting Tips

  • Always log the full response body, not just the HTTP status code. The code and message fields are your most useful debugging signals.
  • Do not retry 4xx errors automatically (except 429). Errors in the 4xx range indicate a problem with the request itself — retrying the same request without fixing the underlying issue will produce the same error.
  • Retry 5xx errors with backoff. Server-side errors are transient in the vast majority of cases.
  • Use the staging environment to reproduce and debug error scenarios without affecting real data. See the Staging Environment guide.
  • Check the Retry-After header on 429 responses before retrying — ignoring it may result in your key being temporarily blocked.