voyageai-cli

# HTTP Status Codes The API uses standard HTTP status codes to indicate the outcome of requests. Proper status code handling is essential for robust client implementations. ## 2xx Success **200 OK**: Request succeeded. Response includes data. ``` GET /users/user_123 200 OK {"data": {"id": "user_123", ...}} ``` **201 Created**: Resource was successfully created. ``` POST /users 201 Created {"data": {"id": "user_456", ...}} Location: /users/user_456 ``` Include the `Location` header for newly created resources. **204 No Content**: Request succeeded, but there's no response body. ``` DELETE /users/user_123 204 No Content (empty response body) ``` Don't expect JSON in 204 responses. ## 3xx Redirection **301 Moved Permanently**: Resource moved to new location (rare in APIs). **304 Not Modified**: Resource hasn't changed since your last request (conditional GET). ``` GET /users/user_123 If-None-Match: "etag_abc" 304 Not Modified (empty response body) ``` ## 4xx Client Error **400 Bad Request**: Invalid request (malformed syntax, missing fields, invalid parameters). ``` POST /users {"name": ""} // Missing required field 400 Bad Request {"error": {"code": "validation_error", ...}} ``` Check response body for specific validation errors. **401 Unauthorized**: Missing or invalid authentication. ``` GET /users (No Authorization header) 401 Unauthorized {"error": {"code": "authentication_required", ...}} ``` Include valid access token in Authorization header. **403 Forbidden**: Authenticated but not authorized for this resource. ``` GET /admin/reports (User doesn't have admin scope) 403 Forbidden {"error": {"code": "insufficient_scope", ...}} ``` Check required scopes in error response. **404 Not Found**: Resource doesn't exist. ``` GET /users/nonexistent_user 404 Not Found {"error": {"code": "resource_not_found", ...}} ``` Verify resource ID; create the resource if needed. **409 Conflict**: Request conflicts with current state. ``` POST /users {"email": "alice@example.com"} // Email already exists 409 Conflict {"error": {"code": "resource_conflict", ...}} ``` Resolve the conflict (e.g., use different email) before retrying. **422 Unprocessable Entity**: Request is valid but can't be processed. ``` POST /orders {"user_id": "user_123", "total": 0} // Invalid state 422 Unprocessable Entity {"error": {"code": "invalid_operation", ...}} ``` This differs from 400 (syntax is valid, but business logic rejects it). **429 Too Many Requests**: Rate limited. Respect Retry-After header. ``` GET /users?page=1 429 Too Many Requests Retry-After: 5 {"error": {"code": "rate_limit_exceeded", ...}} ``` Wait before retrying; use exponential backoff. ## 5xx Server Error **500 Internal Server Error**: Unexpected server error (not your fault). ``` POST /data/process 500 Internal Server Error {"error": {"code": "internal_error", ...}, "meta": {"request_id": "..."}} ``` Retry with exponential backoff. Include request_id in support tickets. **503 Service Unavailable**: Temporary server issues (maintenance, overload). ``` GET /users 503 Service Unavailable Retry-After: 30 ``` Wait the specified duration before retrying. Check status page for incidents. **504 Gateway Timeout**: Request took too long to process. ``` POST /analytics/report?scope=year 504 Gateway Timeout ``` Reduce query scope or split into smaller requests. ## Status Code Handling Strategies **Idempotent operations** (GET, DELETE, PUT): Safe to retry. **Non-idempotent operations** (POST, PATCH): Use idempotency keys to safely retry: ``` POST /users Idempotency-Key: unique-key-123 ``` Same key + body = same response; safe to retry without duplicating data. ## Status Code Combinations Some combinations are common: | Scenario | Status | Action | |----------|--------|--------| | Invalid credentials | 401 | Re-authenticate | | Expired token | 401 | Refresh token | | Insufficient permissions | 403 | Request broader scopes | | Resource not found | 404 | Verify ID; create if needed | | Duplicate email | 409 | Use different email | | Validation error | 400 | Fix input; check error details | | Rate limited | 429 | Implement backoff | | Server error | 5xx | Retry with exponential backoff | ## Monitoring Status Codes Track status code distribution in your applications: ``` 200 OK: 99.5% 400 Bad Request: 0.3% 401 Unauthorized: 0.1% 500 Internal Server Error: 0.1% ``` High error rates indicate issues to investigate.