Error Reference

Complete catalog of error codes, HTTP statuses, and troubleshooting guidance across all AnyaSelf services.

Every AnyaSelf service returns errors in a consistent envelope. This page documents every error code you can encounter.

Error Envelope

All errors follow this shape:

{
  "error": "ERROR_CODE",
  "message": "Human-readable explanation of what went wrong."
}

Validation errors include field-level details:

{
  "error": "VALIDATION_ERROR",
  "message": "Request validation failed.",
  "details": [
    {
      "loc": ["body", "category"],
      "msg": "value is not a valid enumeration member",
      "type": "value_error"
    }
  ]
}

Global Error Codes

These errors can be returned by any service endpoint.

Code	HTTP Status	Description	What to Do
`NOT_FOUND`	`404`	The requested resource does not exist.	Verify the resource ID is correct and belongs to the specified household.
`FORBIDDEN`	`403`	The authenticated user lacks permission for this action.	Ensure the user is a member of the household. Some actions require `PARENT/GUARDIAN` role.
`UNAUTHORIZED`	`401`	Missing or invalid authentication.	Include a valid `Bearer` JWT in the `Authorization` header. Token may be expired.
`CONFLICT`	`409`	The request conflicts with current resource state.	Check the resource's current state — it may have already been modified.
`BAD_REQUEST`	`400`	The request is malformed or contains invalid data.	Review the `message` field for specifics. Common cause: missing required fields.
`VALIDATION_ERROR`	`422`	Request body failed Pydantic schema validation.	Check the `details` array for field-level errors. Fix the request body and retry.
`INTERNAL_ERROR`	`500`	Unexpected server error.	Retry the request. If persistent, check service logs.
`HTTP_ERROR`	varies	Generic HTTP error from FastAPI.	Check the `message` field for details.

Service-Specific Error Codes

API Gateway

Code	HTTP Status	Endpoint(s)	Description
`CONFLICT`	`409`	`POST /members`	Member already exists in household.
`FORBIDDEN`	`403`	`POST /requests`	Role cannot create purchase requests (e.g., child member).
`FORBIDDEN`	`403`	`POST /requests/{id}/approve`	Action requires `PARENT/GUARDIAN` role.
`FORBIDDEN`	`403`	`POST /requests/{id}/confirm-checkout`	Invalid/expired confirmation token, actor mismatch, or child member.
`FORBIDDEN`	`403`	`POST /requests/{id}/cart-ready`, `POST /requests/{id}/failed`	Missing or invalid internal buy-flow token (`X-Internal-Token`).
`CONFLICT`	`409`	`POST /requests/{id}/approve`	Purchase request is already finalized.
`CONFLICT`	`409`	`POST /requests/{id}/purchase-intents`	Request must be `APPROVED` before creating a purchase intent.
`CONFLICT`	`409`	`POST /requests/{id}/cart-ready`	Request not in a cart-prep eligible state.
`CONFLICT`	`409`	`POST /requests/{id}/confirm-checkout`	Request must be `CART_READY`. Confirmation token already used or missing.

Orchestrator

Code	HTTP Status	Endpoint(s)	Description
`INVALID_STATE`	`409`	`POST /missions/{mId}/chat`	Mission is already completed (`DONE` or `FAILED`).
`INVALID_MISSION_TYPE`	`409`	`POST /internal/hyperbeam/events`	Hyperbeam/takeover events require an `INTERACTIVE` mission type.
`VALIDATION_ERROR`	`400`	`POST /missions/{mId}/events`	Missing required field for event type (e.g., `offerId` for `USER_LIKED_ITEM`, `reason` for `USER_DISLIKED_ITEM`, `sessionId` for takeover events).
`FORBIDDEN`	`403`	`POST /missions/{mId}/chat`	User does not own this mission.

Wardrobe

Code	HTTP Status	Endpoint(s)	Description
`NOT_FOUND`	`404`	All item/outfit endpoints	Wardrobe item, outfit, image, or feed collection not found.
`BAD_REQUEST`	`400`	`POST /items`	`ownerMemberId` is not a household member.
`VALIDATION_ERROR`	`400`	`GET /feed`	Unsupported feed source filter value.
`VALIDATION_ERROR`	`400`	`POST /feed/collections`	Collection name is required.
`CONFLICT`	`409`	`POST /items/{id}/images/{imgId}/confirm`	Image already confirmed — cannot confirm twice.
`UPSTREAM_ERROR`	`502`	`POST /items/{id}/upload-url`	Failed to generate GCS signed upload URL.
`UPSTREAM_ERROR`	`502`	`POST /items/{id}/curate`	Look curation or embedding generation failed upstream.
`SERVICE_UNAVAILABLE`	`503`	`POST /items/{id}/curate`, `POST /outfits`	Outfit curation is not enabled in this environment.
`BAD_REQUEST`	`400`	`POST /items/{id}/curate`	Upload an image before running look curation.

Commerce

Code	HTTP Status	Endpoint(s)	Description
`POLICY_VIOLATION`	`400`	`POST /offers`, `POST /offers/bulk`	Offer URL must include a valid domain. Domain not in allowlist (when `COMMERCE_ENFORCE_DOMAIN_ALLOWLIST=true`).
`NOT_FOUND`	`404`	`GET /offers/{id}`, `PATCH /offers/{id}/status`, `DELETE /offers/{id}`	Offer not found.

VTO (Virtual Try-On)

Code	HTTP Status	Endpoint(s)	Description
`BAD_REQUEST`	`400`	`POST /vto/jobs`	`personImageRef` and `garmentImageRef` are required. OR `memberId` is not a household member.
`NOT_FOUND`	`404`	`GET /vto/jobs/{jobId}`	VTO job not found.

Hyperbeam Bridge

Code	HTTP Status	Endpoint(s)	Description
`UPSTREAM_ERROR`	`502`	`POST /sessions`, `POST /sessions/{id}/terminate`, `POST /sessions/{id}/agent-action`	Hyperbeam Cloud API error — session creation, termination, or action dispatch failed.
`INVALID_STATE`	`409`	`POST /sessions/{id}/takeover`, `POST /sessions/{id}/release`, `POST /sessions/{id}/agent-action`	Session is not in an actionable state (must be `ACTIVE` or `USER_TAKEOVER`).
`UNSIGNED_EVENT`	`401`	`POST /hyperbeam/events`	Event signature required but not provided (when `HYPERBEAM_ENFORCE_EVENT_SIGNATURES=true`).
`INVALID_SIGNATURE`	`401`	`POST /hyperbeam/events`	Event HMAC signature verification failed.
`INVALID_REQUEST`	`400`	`POST /sessions/{id}/agent-action`	`TYPE` action requires non-empty `text`. `NAVIGATE` action requires non-empty `url`.

Headless CartPrep

Code	HTTP Status	Endpoint(s)	Description
`POLICY_VIOLATION`	`400`	`POST /cartprep/jobs`	Offer URL domain not in allowlist (when `CARTPREP_ENFORCE_DOMAIN_ALLOWLIST=true`).
`NOT_FOUND`	`404`	`GET /cartprep/jobs/{jobId}`, `POST /cartprep/jobs/{jobId}/process`	Cart prep job not found.

CartPrep Job Failure Codes (returned in the job's errorCode field, not as HTTP errors):

Code	Meaning
`BLOCKED_BOT_DETECTED`	Site detected bot automation
`SIZE_UNAVAILABLE`	Requested size out of stock
`POPUP_OVERLAY_UNRESOLVED`	Cookie/modal overlay blocked interaction
`LOGIN_REQUIRED`	Site requires authentication
`UNKNOWN_DOM`	Unrecognized page structure
`TIMEOUT`	Page or action timed out
`DOMAIN_NOT_ALLOWED`	URL not in domain allowlist
`SAFETY_VIOLATION`	Action violates safety policy
`INTERNAL_ERROR`	Server-side error

Artifacts & Audit

Code	HTTP Status	Endpoint(s)	Description
`NOT_FOUND`	`404`	`GET /artifacts/{id}`	Artifact not found.
`CONFLICT`	`409`	`POST /artifacts/*`	Artifact with duplicate key already exists.

Error Reference

On this page