Skip to main content

​
Normalized error codes

ModelRoute maps all provider-specific errors into 12 deterministic error codes. Regardless of which provider executes your request, you always receive the same error taxonomy.
CodeHTTP StatusRetryableDescription
INPUT_VALIDATION_ERROR400NoInvalid input parameters. Check the details array for field-level errors.
CONTENT_MODERATION_REJECTED400NoContent was rejected by safety filters. Modify your input.
FILE_NOT_FOUND400NoReferenced file does not exist or has expired. Re-upload the file.
FILE_FORMAT_UNSUPPORTED400NoFile format not supported for this model. Check model documentation.
INSUFFICIENT_BALANCE402NoNot enough balance. Top up your account at the dashboard.
RATE_LIMITED429YesRate limit exceeded. Wait for X-RateLimit-Reset and retry.
MODEL_OVERLOADED503YesModel temporarily at capacity. Retry with exponential backoff.
MODEL_UNAVAILABLE503YesModel temporarily unavailable. Retry shortly.
GENERATION_TIMEOUT504YesGeneration timed out. Retry or use async execution.
GENERATION_FAILED500YesGeneration failed at the provider level. Retry the request.
SERVICE_UNAVAILABLE503YesModelRoute platform temporarily unavailable. Retry shortly.
INTERNAL_ERROR500NoAn unexpected internal error. Contact support with the request_id.

​
Detailed guidance

​
INPUT_VALIDATION_ERROR

{
  "error": {
    "code": "INPUT_VALIDATION_ERROR",
    "message": "Invalid input parameters",
    "retryable": false,
    "details": [
      {
        "field": "input.width",
        "code": "OUT_OF_RANGE",
        "message": "width must be between 256 and 2048"
      }
    ]
  }
}
Action: Fix the input based on the details array and resubmit.

​
CONTENT_MODERATION_REJECTED

{
  "error": {
    "code": "CONTENT_MODERATION_REJECTED",
    "message": "Content was rejected by safety filters",
    "retryable": false
  }
}
Action: Review and modify your input content. This error is deterministic — the same input will always be rejected.

​
FILE_NOT_FOUND

{
  "error": {
    "code": "FILE_NOT_FOUND",
    "message": "Referenced file does not exist or has expired",
    "retryable": false
  }
}
Action: Verify the file reference is correct. If the upload was incomplete, re-upload and use the new file reference.

​
FILE_FORMAT_UNSUPPORTED

{
  "error": {
    "code": "FILE_FORMAT_UNSUPPORTED",
    "message": "File format not supported for this model",
    "retryable": false
  }
}
Action: Convert the file to a supported format. Check the model’s documentation for accepted file types.

​
INSUFFICIENT_BALANCE

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient balance for this operation",
    "retryable": false
  }
}
Action: Top up your balance at app.modelroute.ai. Consider enabling auto-topup to prevent interruptions.

​
RATE_LIMITED

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Please retry shortly",
    "retryable": true
  }
}
Action: Check the X-RateLimit-Reset response header for the reset timestamp. Implement exponential backoff.

​
MODEL_OVERLOADED

{
  "error": {
    "code": "MODEL_OVERLOADED",
    "message": "Model temporarily at capacity. Please retry shortly",
    "retryable": true
  }
}
Action: The model’s providers are temporarily at capacity. Retry with exponential backoff. ModelRoute may automatically route to an alternative provider.

​
MODEL_UNAVAILABLE

{
  "error": {
    "code": "MODEL_UNAVAILABLE",
    "message": "Model temporarily unavailable",
    "retryable": true
  }
}
Action: All providers for this model are temporarily down. Retry after a short delay.

​
GENERATION_TIMEOUT

{
  "error": {
    "code": "GENERATION_TIMEOUT",
    "message": "Generation timed out",
    "retryable": true
  }
}
Action: The provider took too long. Retry the request. For consistently slow models, use async executions.

​
GENERATION_FAILED

{
  "error": {
    "code": "GENERATION_FAILED",
    "message": "Generation failed. Please retry",
    "retryable": true
  }
}
Action: The provider encountered an error during generation. Retry — ModelRoute may route to a different provider.

​
SERVICE_UNAVAILABLE

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable",
    "retryable": true
  }
}
Action: The ModelRoute platform is experiencing issues. Check status.modelroute.ai and retry.

​
INTERNAL_ERROR

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An internal error occurred",
    "retryable": false
  }
}
Action: An unexpected error on our end. Contact support@modelroute.ai with the request_id from the error response.