API Transition: Error Handling
The New API (https://llm-server.ai.t-systems.net/v1) introduces structured error responses, making it easier for applications to identify errors and handle them consistently. Standard HTTP status codes continue to indicate request outcomes, while certain error scenarios now have more specific status codes. For the general error reference, see Error Codes.
What Changes?
Section titled “What Changes?”| Scenario | Legacy API | New API |
|---|---|---|
| Missing API key | 403 | 401 |
| Invalid API key | 401 | 401 |
| Blocked or deactivated key | 401 | 403 |
| Model not found | 404 | 400 for model resolution errors |
| Model access denied | 404 | 403 |
| Rate limit exceeded | 429 | 429 |
| Budget exceeded | 429 | 402 |
| Invalid request | 400, sometimes plain text | 400, structured JSON |
| Provider connection failure | 500 | 502 |
| Provider timeout | 500 | 504 |
Example: Error Response
Section titled “Example: Error Response”The Legacy API typically returns provider error information as a string inside detail. The New API returns structured error information.
{ "detail": "Error: 400 - Bad Request - {\"error\":{\"message\":\"Invalid request parameter\",\"type\":\"invalid_request_error\"}}"}{ "error": { "message": "Invalid request parameter", "type": "invalid_request_error", "code": "invalid_value", "param": "messages[0].role" }}Structured error fields allow applications to access error details without parsing an embedded provider error message.
What You Need to Check
Section titled “What You Need to Check”For standard HTTP error handling: Applications can continue relying on HTTP response status codes.
For custom error handling: Review code that depends on specific status codes, error-message text, or the Legacy API’s detail field.
Use the actual HTTP response status as the primary indicator, and treat error fields such as type, code, and param as optional.
Rate Limiting and Retries
Section titled “Rate Limiting and Retries”The New API distinguishes between provider rate limits, service-level rate limits, and budget restrictions.
| Scenario | HTTP status | Retry information |
|---|---|---|
| Provider rate limit | 429 | Provider-supplied retry information may be available |
| Service-level rate limit | 429 | No Retry-After header; reset information may appear in the error message |
| Budget exceeded | 402 | No Retry-After header; budget information may appear in the error message |
When a provider supplies a Retry-After header and it is forwarded in the response, applications should respect it. For service-level rate limits, implement your own backoff strategy; see Rate Limits.
Budget-related errors should be handled separately and should not trigger automatic retries.
Response Validation
Section titled “Response Validation”Validate the response Content-Type before attempting to parse the response body. Some unsupported API routes or methods may return HTML rather than JSON.
A successful HTTP status alone does not guarantee that the response contains the expected API structure.
Troubleshooting
Section titled “Troubleshooting”When reporting an issue, include the request timestamp, endpoint, HTTP status, and any available request or trace identifier. This helps support investigate requests more efficiently.
For questions or migration support, contact AI@t-systems.com.