Skip to main content
The Fastino API uses standard HTTP status codes to communicate the outcome of every request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate a problem with your request that you can fix. Codes in the 5xx range indicate a server-side issue.

Error response format

Most synchronous API errors use a shared nested error envelope:
Validation failures use the same envelope and add an errors array inside error. Each item identifies the invalid field with location and raw_location and explains the failure in message. Some endpoint families intentionally use different shapes:
  • Billing denials (402, some 403s) return {"code", "message", "resolution_url"} instead of the nested envelope - see 402 and 403 below.
  • Warm-up responses (425) include a Retry-After header. OpenAI-shaped bodies also carry code: "model_warming" - see 425 below.
  • Rate-limit responses (429) add top-level code and scope fields alongside detail, plus X-RateLimit-Scope and X-RateLimit-Code headers - see 429 below.
  • Unhandled server errors (500) return {"error", "message"} rather than the nested envelope.
  • Requests to /v1/messages that carry an anthropic-version header receive an Anthropic-shaped {"type": "error", "error": {"type", "message"}} envelope.

Interactive future failures

An HTTP 4xx means that the server rejected an interactive call before queueing it. A successful queueing response returns a future_id. Poll that future until completed, failed, or cancelled. A queued future with status: "failed" can include error.message; treat error.category as an opaque string rather than a retry rule.

Status codes

400 - Bad Request

The request itself is malformed - invalid JSON, or a query/path parameter of the wrong type. Inference endpoints also return 400 when an input passes schema validation but cannot be served, such as a GLiDE prompt longer than the context window or an image outside the GLiDE image limits. How to fix: Confirm your request body is valid JSON and that query/path parameters match the types documented in the endpoint reference. For an inference input, read error.message and correct the input it names.

GLiDE image errors

POST /v1/systemone returns these 400 responses for an image in state. Each one uses the nested envelope with "type": "invalid_request_error" and "code": null, so match on error.message:
An image_url part without image_url.url fails schema validation instead, and returns 422 with image_url parts require an image_url.url.

401 - Unauthorized

Your request did not include a valid API key, the key has been revoked, or your account has been blocked for billing or fraud review. How to fix: Verify that the X-API-Key header is present and contains your current key. If you recently revoked the key, generate a new one at Settings → API Keys. If your account is blocked, contact support@fastino.ai. See Authentication for setup instructions.

402 - Payment Required

A 402 response means your account is out of spendable credits or a billing action is required before inference can run. All API calls will fail until you add credits or upgrade your plan. Visit Settings → Billing or see Plans & Pricing to resolve this.
Your account does not have sufficient credits to complete the request. The response body’s code field tells you which case applies - most commonly out_of_credits (your included credits are exhausted and there’s no spendable paid balance) or funding_required (your account has never been funded). spend_limit_reached means a daily or monthly spend limit on your team or project was reached, and billing_required means a billing action is needed before inference can run. How to fix: Log in to Fastino, go to Settings → Billing, and top up your balance or upgrade your plan. For spend_limit_reached, raise the limit in billing settings or wait for the window to reset. See Plans & Pricing for plan and credit details.

403 - Forbidden

Your team has reached its plan’s maximum monthly overage spend (code: "credit_ceiling_reached"), or your account needs a verified payment method before running inference (code: "card_required"). How to fix: For a spend-ceiling denial, upgrade your plan at Settings → Billing to raise the ceiling. For a card-verification denial, add a valid payment method. Both responses include a resolution_url pointing directly at the page to resolve them.

404 - Not Found

The resource you requested does not exist. This can happen when a dataset name, training job ID, evaluation ID, project ID, or model ID is misspelled or has been deleted. How to fix: Double-check the ID or name in the request path or body. Use the corresponding GET list endpoint (for example GET /v1/training/jobs, GET /v1/base-models) to confirm the resource exists.

409 - Conflict

The model exists in the catalog but isn’t currently servable - for example, a training-only base model requested for direct inference, or an on-demand deployment that hasn’t finished provisioning after a training job completed. How to fix: Check supports_inference and supports_on_demand_inference for the model via GET /v1/base-models, or retry after the deployment finishes provisioning.

413 - Payload Too Large

The request body - typically a file upload for an evaluation or dataset - exceeds the endpoint’s size limit. How to fix: Check the endpoint reference for its upload size limit and split or compress the payload before retrying.

422 - Unprocessable Entity

The request body failed validation. A required field is missing, a field has the wrong type, or a value is outside the accepted range. How to fix: Review error.message and the entries in error.errors for the specific field that failed. Common causes include:
  • Omitting model or type from POST /v1/training/jobs
  • Sending fewer than 1 or more than 1,000 strings in the inputs array for label-existing endpoints

425 - Too Early

The model is temporarily warming up and isn’t ready to serve inference yet. This is expected on the first request after a period without traffic or against a freshly provisioned on-demand deployment, and it does not mean your request is wrong. Warm-up time depends on the model, so a request can return 425 more than once before it succeeds. Most endpoints return an OpenAI-shaped body with code: "model_warming":
Requests to /v1/messages that carry an anthropic-version header receive an Anthropic-shaped body instead, without a code field:
How to fix: To avoid the retry loop, send X-Fastino-Wait-For-Model: true so the request waits up to 150 seconds for the model, or warm it first with POST /v1/model-status/{model_id}/warm; see Retries and model warm-up. Otherwise, wait Retry-After seconds (30 if the header is missing) and send the same request again, with a bounded number of retries. Each example retries at most 5 times, sets a 300-second client timeout, and stops on any other non-2xx response. The same loop works for /v1/systemone; change the URL and request body.
With an SDK, see Retries and model warm-up for which responses to retry and how to back off.

429 - Too Many Requests

You have exceeded a request-rate limit for this endpoint. The response includes a Retry-After header, plus X-RateLimit-Scope and X-RateLimit-Code headers identifying which limit you hit - the JSON body carries matching code and scope fields alongside detail. How to fix: Respect the Retry-After value and back off before retrying. See Retries and model warm-up for a retry pattern. Note that credit and overage denials return 402/403, not 429.
The requested model isn’t available to your account due to export-control or sanctions restrictions in your region. How to fix: If you believe your access was incorrectly restricted, contact support.

500 - Internal Server Error

An unexpected error occurred on Fastino’s servers. This is not caused by your request. The body uses error and message fields rather than detail:
How to fix: Wait a moment and retry. If the error persists, check status.fastino.ai for live service status or contact support.

503 - Service Unavailable

A dependency the request needed - billing verification, or a provider’s status/metrics endpoint - is temporarily unavailable. How to fix: Wait a moment and retry. If the error persists, check status.fastino.ai for live service status or contact support.

529 - Overloaded (Anthropic-compatible endpoint only)

POST /v1/messages mirrors Anthropic’s own overloaded_error response when upstream Claude capacity is temporarily saturated. How to fix: Retry with backoff, the same as you would for a 429 or 503.