Auth and errors

Current auth model, error contract, and production hardening checklist

No built-in auth

API routes currently do not require API keys, JWTs, or wallet signatures.

Stable error envelope

Errors return a consistent JSON body with code and message.

Gateway required

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

Error payload shape

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

error · object · required

Top-level error object.

code · string · required

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

message · string · required

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

1. Add auth at the edge

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

2. Add rate limiting

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

3. 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.