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:

{
  "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.

Example error response

{
  "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.

Overview

Inference API

Chat Agents API

Using the API

Error response format

Error message example

Error categories

Error code reference

​Error response format

​Error message example

​Error categories

​Error code reference

Error response format

Error message example

Error categories

Error code reference