The SambaCloud 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. These include:
  • Error code
    • Identifies the type of error.
  • Parameter (if applicable)
    • Specifies the property causing the error.
  • Error message
    • Provides a clear explanation of the issue.

​
Error message

This error message 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 message
{
  "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"
  }
}

​
Error categories

Use the following table to understand the various error categories.
HTTP statusCategoryDescriptionSuggestion
400Bad requestThe server couldn’t process the request due to invalid syntax or input values.Review the API request syntax and parameters.
401UnauthorizedAuthentication credentials are missing or invalid.Ensure valid API key/token is included.
408Request timeoutThe server terminated the request due to excessive processing time.Retry the request with optimized payload.
410GoneThe requested model is no longer available (deprecated or removed).Use a currently supported model.
429Too many requestsRate limit exceeded for your subscription tier.Implement rate limiting or upgrade tier.
429Queue FullToo many requests are currently in flight; the server declined the request.Retry after a short delay or reduce concurrency.
500Something went wrongA server-side error occurred.Retry later or contact support if persistent.
503MaintenanceThe 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 statusError codeDescriptionSuggestion
400context_length_exceededInput/output tokens exceed model context limits.Reduce prompt and response length to stay within model limits.
invalid_typeParameter type mismatch (e.g., expected int but got float).Check the expected parameter types and correct the input.
decimal_above_max_valueDecimal value exceeds the allowed maximum.Adjust the value to fall within the allowed range.
decimal_below_min_valueDecimal value is below the allowed minimum.Increase the value to meet the minimum required threshold.
integer_above_max_valueInteger value exceeds the allowed maximum.Provide a smaller integer within the valid range.
model_not_foundProvided model ID does not exist.Verify the model ID and ensure it’s available in your subscription.
401invalid_authenticationInvalid or expired API key.Generate and use a valid API key from the SambaCloud portal.
408request_timeoutRequest 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.
410model_deprecatedThe requested model has been deprecated and is no longer available.Use a currently supported model listed in the documentation.
429insufficient_quotaRate limit exceeded.Upgrade your plan for higher quota.
429queue_fullToo many in-flight requests; server declined the request.Retry after a delay or reduce request frequency.
500internal_server_errorAn unexpected server-side error occurred.Retry later. If the issue persists, contact support.
503maintenanceModel is temporarily unavailable due to maintenance.Try again after some time or check maintenance announcements.