> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thiqwave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Codes

> Understand how Thiqwave returns errors and how to handle them in your integration.

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:

| Field     | Type   | Description                                          |
| --------- | ------ | ---------------------------------------------------- |
| `error`   | string | A short, machine-readable error identifier           |
| `message` | string | A human-readable description of what went wrong      |
| `code`    | string | An application-level code for precise error handling |

```json theme={null}
{
  "error": "Unauthorized",
  "message": "The API key provided is invalid or has been revoked.",
  "code": "INVALID_API_KEY"
}
```

***

## HTTP Status Codes

<AccordionGroup>
  <Accordion title="400 Bad Request">
    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
  </Accordion>

  <Accordion title="401 Unauthorized">
    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
  </Accordion>

  <Accordion title="403 Forbidden">
    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
  </Accordion>

  <Accordion title="404 Not Found">
    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)
  </Accordion>

  <Accordion title="409 Conflict">
    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](/reference/idempotency) guide for details on how to handle key conflicts.
  </Accordion>

  <Accordion title="422 Unprocessable Entity">
    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
  </Accordion>

  <Accordion title="429 Too Many Requests">
    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](/reference/rate-limits) for current limits and guidance on handling this response.
  </Accordion>

  <Accordion title="500 Internal Server Error">
    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](/reference/rate-limits#handling-429-responses).
  </Accordion>
</AccordionGroup>

***

## Application Error Codes

The `code` field in the error body provides a more specific identifier that you can use in your error-handling logic.

<AccordionGroup>
  <Accordion title="INVALID_API_KEY">
    **HTTP status:** `401`

    The API key in the `X-API-Key` header is missing, malformed, or has been revoked. Retrieve a valid key from the [Thiqwave Dashboard](https://console.thiqwave.com) under **Settings → API Keys**.
  </Accordion>

  <Accordion title="RATE_LIMIT_EXCEEDED">
    **HTTP status:** `429`

    Your 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.
  </Accordion>

  <Accordion title="VALIDATION_FAILED">
    **HTTP status:** `422`

    One 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.
  </Accordion>

  <Accordion title="RESOURCE_NOT_FOUND">
    **HTTP status:** `404`

    The requested resource does not exist. Check that the resource ID in the path is correct and that you are targeting the right environment.
  </Accordion>

  <Accordion title="COMPLIANCE_REQUIRED">
    **HTTP status:** `403`

    The 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.
  </Accordion>

  <Accordion title="TRANSACTION_FAILED">
    **HTTP status:** `422`

    The 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.
  </Accordion>

  <Accordion title="INSUFFICIENT_PERMISSIONS">
    **HTTP status:** `403`

    Your 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.
  </Accordion>
</AccordionGroup>

***

## 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:

```json theme={null}
{
  "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](/guides/environments) guide.
* **Check the `Retry-After` header** on `429` responses before retrying — ignoring it may result in your key being temporarily blocked.