Errors

The API uses the usual HTTP statuses: 2xx success, 4xx request error, 5xx service error. Every error has the same format:

JSON

{
  "error": {
    "code": "validation_failed",
    "message": "`threshold` is required for `large_transfer`.",
    "details": { "field": "threshold" }
  }
}

Field	Meaning
`code`	Stable identifier, in `snake_case`. Program against this field: it never changes within v1.
`message`	English explanation for the developer. The text may be improved without notice: do not parse it, and do not show it as is to your end users.
`details`	Object, possibly empty, with what you need to fix the request (faulty field, limit reached, rules involved…).

v1 can add new codes: handle an unknown code according to its HTTP status.

Codes by status#

400 Bad request#

Code	Cause
`invalid_body`	Malformed JSON body (`details.reason`).
`invalid_query`	Invalid query parameter: `limit`, `cursor`, date, `severity`, `status`, `state`… (`details.field`).
`invalid_idempotency_key`	Empty, too long or non-ASCII `Idempotency-Key`.

401 Unauthenticated#

Code	Cause
`missing_api_key`	No `Authorization: Bearer` header.
`invalid_api_key`	Unknown or malformed key.
`api_key_revoked`	Revoked key.
`api_key_expired`	Expired key.

403 Forbidden#

Code	Cause
`insufficient_scope`	The key lacks the required scope (`details.required_scope`, `details.key_scopes`).
`workspace_suspended`	Suspended workspace.
`account_under_review`	Owner account under review (`details.reason`).
`plan_required`	The plan does not include the API (`details.plan`).
`plan_limit_reached`	Plan limit reached (`details.resource`: `addresses`, `rules`, `channels`, `chains`; `limit`, `current`, `plan`).
`plan_feature_unavailable`	Feature not included in the plan, e.g. `immediate_alert` (`details.feature`).
`channel_kind_not_in_plan`	Channel kind not included in the plan (`details.allowed_kinds`).

404, 405#

Code	Cause
`not_found`	Resource that does not exist, belongs to another workspace, or malformed id; unknown route.
`method_not_allowed`	Method not allowed on this resource.

409 Conflict#

Code	Cause
`address_already_watched`	Address already watched on this chain (`details.id`: its id).
`address_in_use`	Address used by active rules (`details.rules`): pause them first.
`channel_in_use`	Channel used by active rules (`details.rules`).
`channel_inactive`	Disabled channel: enable it before a test or a resend.
`change_already_pending`	A deferred pause or deletion is already waiting on this rule.
`notification_already_queued`	Notification already queued for delivery.
`notification_grouped`	Alert counted in a digest: resend the digest (`details.notification_id`).
`idempotency_in_progress`	A request with the same `Idempotency-Key` is still running (`Retry-After: 1`).

413, 415#

Code	Cause
`payload_too_large`	Body over 1 MiB on a request with `Idempotency-Key`.
`unsupported_media_type`	Body without `Content-Type: application/json`.

422 Invalid data#

Code	Cause
`validation_failed`	Invalid field (`details.field`); body that does not match the schema: missing required field, wrong type or unknown field (`details.reason`); unknown chain or channel.
`url_not_allowed`	Webhook URL refused by the SSRF protection (`details.reason`).
`idempotency_key_reused`	`Idempotency-Key` already used for a different request.

Request bodies reject unknown fields: a typo in a field name gives 422 validation_failed rather than a silently ignored field.

429 Too many requests#

Code	Cause
`rate_limited`	Per-second rate of the key exceeded (`Retry-After: 1`).
`daily_quota_exceeded`	Daily quota of the plan reached (`Retry-After` until midnight UTC).

5xx Service error#

HTTP	Code	Cause
500	`internal_error`	Internal error. Retry later; write to support@aicscan.io if it persists.
503	`channel_kind_unavailable`	Channel kind (Telegram or helloMe) temporarily unavailable on the service.

What to do by status#

Status	Retry?
`400`, `401`, `403`, `404`, `405`, `413`, `415`, `422`	No: fix the request, the key or the plan.
`409`	Depends on the code: `idempotency_in_progress` yes, after `Retry-After`; the others need an action.
`429`	Yes, after `Retry-After`.
`500`, `502`, `503`, `504`	Yes, with increasing delays, and the same `Idempotency-Key` for a `POST`.

Getting help#

If an error persists or cannot be explained, write to support@aicscan.io with your workspace name, the route called, the time (UTC), the HTTP status and the code received, plus the key prefix (aic_k3J9xQ2a). Never send the full key: if in doubt, revoke it from the API keys page.