Error Codes

Standardized error format and all possible error codes.

Error Format

All errors follow this structure:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "content is required and must be a string",
    "details": {}
  }
}

The details field is optional and provides additional context when available.

Error Codes

PAYMENT_REQUIRED (402)

Missing or invalid x402 payment header. Returned when no payment proof is provided, or the payment is invalid/expired.

{
  "error": {
    "code": "PAYMENT_REQUIRED",
    "message": "Valid x402 payment required"
  }
}

UNAUTHORIZED (401)

Invalid or missing authentication. Returned when wallet address cannot be extracted from payment proof.

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Could not extract wallet address from payment"
  }
}

NOT_FOUND (404)

Resource not found. Returned when trying to access or delete a memory that doesn’t exist, was already deleted, or belongs to a different wallet.

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Memory not found"
  }
}

VALIDATION_ERROR (422)

Invalid request body. Returned when the request fails validation — missing required fields, exceeding limits, or wrong types. Includes details when available.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "content must be at most 8192 characters",
    "details": {
      "max_length": 8192,
      "actual_length": 9500
    }
  }
}

RATE_LIMIT_EXCEEDED (429)

Rate limit exceeded. Includes limit and reset time in details.

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded",
    "details": {
      "limit": 100,
      "reset_at": "2025-01-15T12:00:00Z"
    }
  }
}

INTERNAL_ERROR (500)

Server error. Something went wrong on our end. If persistent, check the /health endpoint.

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred"
  }
}