> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sambanova.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API error codes

The SambaNova API uses standard HTTP response status codes to indicate whether an API request was successful or failed.

When a request fails, the API responds with a JSON object containing details about the error. The response follows the OpenAI error format with an additional `request_id` field for tracing.

## Error response format

All error responses have the following structure:

```json theme={}
{
  "error": {
    "message": "<human-readable description of the error>",
    "type": "<error type>",
    "param": "<parameter that caused the error, or null>",
    "code": "<error code, or null>"
  },
  "request_id": "<unique identifier for this request>"
}
```

| Field | Description |
| - | - |
| `error.message` | Human-readable explanation of the error |
| `error.type` | Category of the error (for example, `invalid_request_error`) |
| `error.param` | The request parameter that caused the error, if applicable |
| `error.code` | Machine-readable error code for programmatic handling, if applicable |
| `request_id` | Unique identifier for the request. Provide this to SambaNova support when reporting issues. |

## Error message example

This error indicates that a parameter value exceeded the allowed maximum. The `top_p` parameter received a value of `100`, whereas it should be between `0` and `1`. The error type is `invalid_request_error`, with the code `decimal_above_max_value`.

```json Example error response theme={}
{
  "error": {
    "message": "Decimal above maximum value. Expected a value between 0 and 1, but got 100 instead.",
    "type": "invalid_request_error",
    "param": "top_p",
    "code": "decimal_above_max_value"
  },
  "request_id": "2a8b3c4d-1234-5678-abcd-ef0123456789"
}
```

## Error categories

Use the following table to understand the various error categories.

| HTTP status | Category | Description | Suggestion |
| :- | :- | :- | :- |
| 400 | Bad request | The server couldn't process the request due to invalid syntax or input values. | Review the API request syntax and parameters. |
| 401 | Unauthorized | Authentication credentials are missing or invalid. | Ensure valid API key/token is included. |
| 408 | Request timeout | The server terminated the request due to excessive processing time. | Retry the request with optimized payload. |
| 410 | Gone | The requested model is no longer available (deprecated or removed). | Use a currently supported model. |
| 429 | Too many requests | Rate limit exceeded for your subscription tier. | Implement rate limiting or upgrade tier. |
| 429 | Queue Full | Too many requests are currently in flight; the server declined the request. | Retry after a short delay or reduce concurrency. |
| 500 | Something went wrong | A server-side error occurred. | Retry later or contact support if persistent. |
| 503 | Maintenance | The model is temporarily unavailable due to maintenance. | Try again after some time. |

## Error code reference

Use the following table to understand and troubleshoot errors programmatically.

| HTTP status | Error code | Description | Suggestion |
| :- | :- | :- | :- |
| 400 | `context_length_exceeded` | Input/output tokens exceed model context limits. | Reduce prompt and response length to stay within model limits. |
| | `invalid_type` | Parameter type mismatch (e.g., expected int but got float). | Check the expected parameter types and correct the input. |
| | `decimal_above_max_value` | Decimal value exceeds the allowed maximum. | Adjust the value to fall within the allowed range. |
| | `decimal_below_min_value` | Decimal value is below the allowed minimum. | Increase the value to meet the minimum required threshold. |
| | `integer_above_max_value` | Integer value exceeds the allowed maximum. | Provide a smaller integer within the valid range. |
| | `model_not_found` | Provided model ID does not exist. | Verify the model ID and ensure it’s available in your subscription. |
| 401 | `invalid_authentication` | Invalid or expired API key. | Generate and use a valid API key from the SambaCloud portal. |
| 408 | `request_timeout` | Request timed out due to server load or latency. | Retry with a smaller or optimized request payload. Additionally, consider upgrading to a higher subscription tier to avoid this. |
| 410 | `model_deprecated` | The requested model has been deprecated and is no longer available. | Use a currently supported model listed in the documentation. |
| 429 | `insufficient_quota` | Rate limit exceeded. | Upgrade your plan for higher quota. |
| 429 | `queue_full` | Too many in-flight requests; server declined the request. | Retry after a delay or reduce request frequency. |
| 500 | `internal_server_error` | An unexpected server-side error occurred. | Retry later. If the issue persists, contact support. |
| 503 | `maintenance` | Model is temporarily unavailable due to maintenance. | Try again after some time or check maintenance announcements. |