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

# Errors

> Reference for Webacy API errors, including HTTP status codes, standardized error response fields, and troubleshooting steps for common failure cases.

Every Webacy API response includes an appropriate HTTP status code. When an error occurs, the API returns a structured JSON response describing what happened and, where possible, how to resolve it.

Applications should always check the HTTP status code before processing the response body.

## Common HTTP Status Codes

| Status | Meaning |
| - | - |
| **200 OK** | Request completed successfully. |
| **400 Bad Request** | The request was malformed or contains invalid parameters. |
| **401 Unauthorized** | Authentication failed or the API key is invalid. |
| **402 Payment Required** | Payment is required before the request can be served. Endpoints that support keyless [x402 payments](/x402-payments) return this with a `payment-required` challenge when there is no prepaid balance. Requests authenticated with an API key can also receive a `402` when the account has an outstanding subscription balance. |
| **403 Forbidden** | The authenticated account does not have permission to access the requested resource. This means your API key does not have access to the endpoint you are trying to call. Some endpoints require a higher plan tier. See [Endpoint Access by Plan](/rate-limits#endpoint-access-by-plan). |
| **404 Not Found** | The requested resource or endpoint does not exist. |
| **409 Conflict** | The request conflicts with the current state of the resource. |
| **422 Unprocessable Entity** | The request was valid but could not be processed (for example, an unsupported blockchain entity or invalid address format). |
| **429 Too Many Requests** | Your application has exceeded its rate limit or monthly usage allocation. |
| **500 Internal Server Error** | An unexpected server error occurred. |
| **503 Service Unavailable** | The service is temporarily unavailable or undergoing maintenance. |

## Handling Errors

Applications should be designed to handle errors gracefully.

We recommend:

* Validate user input before sending requests.
* Retry temporary failures such as `429` and `503` using exponential backoff.
* Do not retry authentication (`401`) or malformed request (`400`) errors without first correcting the request.
* Log error responses for troubleshooting and monitoring.
* Display meaningful error messages to end users when appropriate.

## Support

If you receive unexpected errors or believe an issue is not documented, email the Webacy team at [info@webacy.com](mailto:info@webacy.com). Include the request ID, endpoint, timestamp, and full error response so we can investigate the issue more quickly.

## Reporting a security issue

To report a suspected security vulnerability in the Webacy API, SDKs, or dApp, email [info@webacy.com](mailto:info@webacy.com) with the subject line `Security report`. Include:

* A description of the vulnerability and its potential impact.
* Steps to reproduce, including any proof-of-concept requests or payloads.
* Affected endpoint, SDK version, or URL.
* The date and time you observed the issue, in UTC.

Do not include real user data, private keys, or third-party credentials in the report. Please give us a reasonable window to investigate and respond before disclosing the issue publicly.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.