The MARA Cloud API uses standard HTTP status codes to indicate whether a request succeeded or failed. When a request fails, the API returns a JSON object with details about the error.
Error response format
Every error response includes the following fields:
json
{
"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"
}
}| Field | Description |
|---|---|
message | A human-readable explanation of what went wrong. |
type | The category of error (e.g., invalid_request_error). |
param | The specific parameter that caused the error (if applicable). |
code | A machine-readable error code for programmatic handling. |
Error categories
| HTTP Status | Category | Description | What to do |
|---|---|---|---|
| 400 | Bad request | The request contained invalid syntax or parameter values. | Review your request parameters against the API documentation. |
| 401 | Unauthorized | Authentication credentials are missing or invalid. | Check that your API key is valid and included in the Authorization header. |
| 408 | Request timeout | The server terminated the request due to excessive processing time. | Retry with a smaller payload or implement exponential backoff. |
| 410 | Gone | The requested model has been deprecated or removed. | Switch to a supported model from the Model Catalog. |
| 429 | Too many requests | You've exceeded the rate limit for your tier. | Implement rate limiting, retry after a delay, or upgrade your tier. See Rate Limits. |
| 500 | Internal server error | Something went wrong on our end. | Retry later. If persistent, contact support. |
| 503 | Maintenance | The model is temporarily unavailable. | Wait and retry. |
Error code reference
Detailed error codes for programmatic error handling.
400 - Bad request
| Error Code | Description | What to do |
|---|---|---|
context_length_exceeded | Input and output tokens exceed the model's context window. | Reduce prompt length or lower max_tokens. Check context limits in the Model Catalog. |
invalid_type | A parameter received the wrong type (e.g., float instead of int). | Verify parameter types against the API Reference. |
decimal_above_max_value | A decimal parameter exceeds its maximum allowed value. | Adjust the value to fall within the documented range. |
decimal_below_min_value | A decimal parameter is below its minimum allowed value. | Increase the value to meet the minimum threshold. |
integer_above_max_value | An integer parameter exceeds its maximum allowed value. | Provide a smaller value within the valid range. |
model_not_found | The specified model ID does not exist. | Verify the model ID against the Model Catalog. |
401 - Unauthorized
| Error Code | Description | What to do |
|---|---|---|
invalid_authentication | The API key is invalid or expired. | Generate a new key from the MARA Cloud portal. See API Keys and URLs. |
408 - Request timeout
| Error Code | Description | What to do |
|---|---|---|
request_timeout | The request took too long to process. | Retry with a smaller or optimized payload. Consider reducing prompt length. |
410 - Gone
| Error Code | Description | What to do |
|---|---|---|
model_deprecated | The model has been deprecated and is no longer available. | Migrate to a supported model. See Model Deprecations. |
429 - Too many requests
| Error Code | Description | What to do |
|---|---|---|
insufficient_quota | Rate limit exceeded for your current tier. | Wait for the reset window or upgrade your plan. See Rate Limits. |
queue_full | Too many requests in flight. The server declined the request. | Retry after a short delay or reduce concurrency. |
500 - Internal server error
| Error Code | Description | What to do |
|---|---|---|
internal_server_error | An unexpected error occurred on the server. | Retry later. If the issue persists, contact support. |
503 - Service unavailable
| Error Code | Description | What to do |
|---|---|---|
maintenance | The model is temporarily unavailable due to maintenance. | Wait and retry. |
Best practices
- Implement exponential backoff for retryable errors (408, 429, 500, 503). See the retry example in Rate Limits.
- Validate inputs against documented constraints before making requests.
- Check error codes programmatically rather than parsing error messages, as messages may change.
- Log errors with the full response body for debugging.