Auth and errors

Optional API key auth

Write endpoints require an API key when API_KEY is configured in the environment.

TE

Stable error envelope

Errors return a consistent JSON body with code and message.

SH

Gateway required

Put auth and throttling in front of this API for production workloads.

Error payload shape

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid hex: ..."
  }
}

errorobjectrequired

Top-level error object.

codestringrequired

Machine-readable code such as BAD_REQUEST, VALIDATION_ERROR, IPFS_ERROR.

messagestringrequired

Human-readable description derived from server-side error mapping.

HTTP status mapping

Condition	HTTP	Example codes
Bad input or invalid hex	400	BAD_REQUEST
Validation failure	422	VALIDATION_ERROR
ENS/SuiNS record not found	404	ENS_NAME_NOT_FOUND, SUINS_NAME_NOT_FOUND
IPFS gateway/download failure	502	IPFS_ERROR
Unhandled internal failure	500	INTERNAL_ERROR

Real response examples

400 bad request

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid meta_address: ..."
  }
}

404 name not found

{
  "error": {
    "code": "ENS_NAME_NOT_FOUND",
    "message": "ENS name not found: alice.eth"
  }
}

502 IPFS error

{
  "error": {
    "code": "IPFS_ERROR",
    "message": "IPFS download failed: HTTP 403"
  }
}

Production hardening path

01

Add auth at the edge

Require API key or wallet-authentication in your reverse proxy or API gateway.

02

Add rate limiting

Throttle by IP and route group, especially on /api/v1/stealth/* scan endpoints.

03

Log error codes

Track error.code values for alerting and integration diagnostics.

Where error codes come from

ApiError maps from SpecterError in specter-api/src/error.rs and produces the final JSON envelope.

Why 422 and 400 both exist

Validation errors from typed domain checks use 422, while malformed request values and parse failures use 400.