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 nestederror envelope:
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, some403s) return{"code", "message", "resolution_url"}instead of the nested envelope - see 402 and 403 below. - Warm-up responses (
425) include aRetry-Afterheader. OpenAI-shaped bodies also carrycode: "model_warming"- see 425 below. - Rate-limit responses (
429) add top-levelcodeandscopefields alongsidedetail, plusX-RateLimit-ScopeandX-RateLimit-Codeheaders - see 429 below. - Unhandled server errors (
500) return{"error", "message"}rather than the nested envelope. - Requests to
/v1/messagesthat carry ananthropic-versionheader receive an Anthropic-shaped{"type": "error", "error": {"type", "message"}}envelope.
Interactive future failures
An HTTP4xx 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 return400 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 theX-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
Your account does not have sufficient credits to complete the request. The response body’scode 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 correspondingGET 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: Checksupports_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: Reviewerror.message and the entries in error.errors for the specific field that failed. Common causes include:
- Omitting
modelortypefromPOST /v1/training/jobs - Sending fewer than 1 or more than 1,000 strings in the
inputsarray 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 return425 more than once before it succeeds.
Most endpoints return an OpenAI-shaped body with code: "model_warming":
/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.
429 - Too Many Requests
You have exceeded a request-rate limit for this endpoint. The response includes aRetry-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.
451 - Unavailable for Legal Reasons
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 useserror and message fields rather than detail:
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.
