Skip to content

Document actual error response format from Artemis #12

Closed

Description

@suparious

Description

The error documentation should reflect the actual error response format returned by Artemis/LiteLLM, not just theoretical OpenAI-compatible errors.

Current State

src/content/docs/api/errors.md (if it exists) likely documents generic OpenAI error format.

Required Content

  1. Actual Error Responses

    • Verify the exact JSON structure returned by Artemis
    • Document all error types actually used in production
  2. Error Categories

    • Authentication Errors (401)

      • Invalid API key
      • Missing Authorization header
      • Expired key
    • Validation Errors (400)

      • Invalid model name
      • Missing required fields
      • Invalid parameter types
    • Rate Limit Errors (429)

      • Rate limit response format
      • Retry-After header
    • Server Errors (500)

      • vLLM unavailable (failover to Claude)
      • Internal errors
  3. Error Handling Examples

    try:
        response = client.chat.completions.create(...)
    except AuthenticationError as e:
        # Handle invalid API key
    except RateLimitError as e:
        # Handle rate limit
  4. Failover Behavior

    • Document that chat completions fail over to Claude Haiku when vLLM is down
    • Users should be aware of potential model changes during outages

Acceptance Criteria

  • Error documentation matches actual Artemis response format
  • All HTTP status codes documented (400, 401, 429, 500, 503)
  • Real-world error examples from production
  • Python error handling examples
  • JavaScript error handling examples
  • Documents failover behavior

Priority

MEDIUM - Important for production robustness.

Activity

  1. suparious commented on Jan 18, 2026

    @suparious
    MemberAuthor

    Fixed in commit 3a17542

    Changes made to src/content/docs/api/errors.md:

    Added:

    • Actual Artemis Gateway error response format documentation
    • All HTTP status codes with retry guidance (400, 401, 403, 404, 422, 429, 500, 502, 503, 504)
    • Authentication errors (invalid key, missing header)
    • Validation errors (invalid model, missing fields, invalid types)
    • Rate limit error format with headers
    • Server errors including failover scenarios
    • Failover behavior documentation - explains automatic failover from vLLM to Claude Haiku
    • Complete Python error handling example with proper retry logic
    • Complete JavaScript/TypeScript error handling example
    • Failover architecture diagram
    • Comparison table of primary vs fallback model characteristics

    All acceptance criteria have been addressed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions