Errors

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 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.
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 Compute Unit 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. 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 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.

👋 Start Here

Integrations

Vaults

Stablecoin & RWA

Depeg Monitor

Glossary

Common HTTP Status Codes

Handling Errors

Support

Reporting a security issue

​Common HTTP Status Codes

​Handling Errors

​Support

​Reporting a security issue

Common HTTP Status Codes

Handling Errors

Support

Reporting a security issue