Skip to main content
The Pioneer 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 error responses return a JSON body with a detail field:
A few response families use a different shape:
  • Billing denials (402, some 403s) return {"code", "message", "resolution_url"} instead of detail — see 402 and 403 below.
  • Rate-limit responses (429) add 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 detail.
  • Requests against the OpenAI-compatible endpoints (/v1/chat/completions, /v1/completions, /v1/responses, /v1/embeddings) receive an OpenAI-shaped {"error": {"code", "type", "param", "message"}} envelope, and requests carrying an anthropic-version header receive an Anthropic-shaped {"type": "error", "error": {"type", "message"}} envelope instead of the generic shapes above.

​
Status codes

​
400 — Bad Request

The request itself is malformed — invalid JSON, or a query/path parameter of the wrong type. How to fix: Confirm your request body is valid JSON and that query/path parameters match the types documented in the endpoint reference.

​
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@pioneer.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 direct_model_requires_credits (calling a supported model directly requires a paid credit balance). How to fix: Log in to pioneer.ai, go to Settings → Billing, and top up your balance or upgrade your plan. See Credit limits and overage spending cap for how credit limits and overage billing work.

​
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 /felix/training-jobs, GET /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 /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 the error message for the specific field that failed. Common causes include:
  • Omitting base_model from POST /felix/training-jobs
  • Passing an unsupported task_type to POST /generate
  • Sending fewer than 1 or more than 1,000 strings in the inputs array for label-existing endpoints

​
425 — Too Early

The requested on-demand deployment is still warming up (cold-starting) and isn’t ready to serve inference yet. How to fix: Respect the Retry-After header and retry after the given delay. This is expected on the first request against a freshly provisioned on-demand deployment.

​
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 Rate Limits for per-endpoint limits and a retry code pattern. Note that credit and overage denials return 402/403, not 429 — see Credit limits and overage spending cap.
The requested model isn’t available to your account due to export-control or sanctions restrictions in your region. How to fix: See the FAQ for the current list of restricted regions and provider-specific policies. If you believe your access was incorrectly restricted, contact support.

​
500 — Internal Server Error

An unexpected error occurred on Pioneer’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.pioneer.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.pioneer.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.