Auth and errors

Optional API key auth

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

Stable error envelope

Errors return a consistent JSON body with code and message.

Gateway required

Configure API_KEY, CORS, rate limits, and body limits before 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`
Missing or invalid API key	`401`	`UNAUTHORIZED`
Resource or dedup conflict	`409`	`CONFLICT`
Validation failure	`422`	`VALIDATION_ERROR`
Rate limit exceeded	`429`	`RATE_LIMITED`
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
404 name not found
502 IPFS error

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

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

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

Production hardening path

Add auth at the edge

Set API_KEY and include it on mutating requests as the X-API-Key header.

Add rate limiting

Use the built-in per-IP rate limiter (RATE_LIMIT_RPS, RATE_LIMIT_BURST) and add edge throttling if your deployment needs stricter route-level controls.

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. With API_KEY configured, internal error messages are sanitized to An internal error occurred.

Why 422 and 400 both exist

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