Errors - Convexity Infra API

All services report failures through the same envelope, so you can handle errors uniformly regardless of which endpoint you called.

Error shape

{
  "status": false,
  "message": "Wallet not found"
}

Validation failures add an errors array of field-level messages:

{
  "status": false,
  "message": "Validation failed",
  "errors": [
    "webhookUrl: Invalid url"
  ]
}

Field	Type	Description
`status`	`boolean`	Always `false` on error.
`message`	`string`	Human-readable error summary.
`errors`	`string[]`	Optional. Per-field validation messages (`field: message`).

Token endpoint is differentPOST /v1/oauth/token returns OAuth 2.0 error bodies ({ "error", "error_description" }) rather than this envelope. See Authentication.

Status codes

Status	Meaning	Typical cause
`200 OK`	Success	Request completed.
`201 Created`	Created	A new resource (subscription, transfer) was created.
`202 Accepted`	Accepted	Work was queued (e.g. webhook resend).
`400 Bad Request`	Invalid input	Malformed parameter, body, or unsupported value.
`401 Unauthorized`	Not authenticated	Missing/invalid token, or missing project/business context.
`402 Payment Required`	Insufficient funds	Wallet balance cannot cover estimated gas.
`403 Forbidden`	Not authorized	Test token used, missing capability, or cross-business access.
`404 Not Found`	No such resource	Unknown id, or a resource not owned by your project.
`422 Unprocessable Entity`	Semantic failure	Validation passed but the operation failed (e.g. transfer reverted).
`429 Too Many Requests`	Rate limited	Throttle exceeded; honour `retryAfter`.
`503 Service Unavailable`	Upstream issue	Dependency (e.g. gas pricing) temporarily unavailable; retry.

Common error messages

Status	Message	Where
`401`	`Authorization token is missing or malformed.`	Any guarded endpoint.
`401`	`Invalid token`	Token failed verification.
`401`	`Token is missing project or business context`	Token lacks the required claims.
`403`	`Test tokens are not allowed, please use your live api key.`	Business endpoints.
`403`	`Missing required capability: <capability>`	Blockchain Events endpoints.
`403`	`Unauthorized: Cannot access wallet from other business`	Wallet endpoints.
`404`	`<Resource> not found`	Lookups by id.

Retry strategyRetry 429 after the retryAfter interval, and retry 503 after a short backoff. Do not retry 400, 401, 403, 404, or 422 without changing the request.