How do I fix common ModelRiver API errors?
Most errors come from a key, a workflow name or a limit. Find your status code below and check the listed cause first.
401: authentication error#
The API key is wrong, expired or revoked.
- Send it as
Authorization: Bearer mr_live_.... - Make sure it hasn't expired or been revoked under Settings → API Keys.
403: forbidden#
The key belongs to a different project or is no longer active. Create a key in the project you're calling. Deleting a session in a protected project through the API also gives a 403; an Owner or Admin can delete it in the console.
404: model_not_found#
The workflow name doesn't match. Names are case-sensitive, and the workflow must be in the same project as the API key.
400: model_not_supported#
You called a backend pipeline workflow (one with an event name) synchronously. Use POST /v1/ai/async, or remove the event name.
422: session_not_found#
The session_id belongs to another project or workflow, or was deleted. Start a new conversation without a session_id.
429: rate limit exceeded#
You sent more requests per minute than your plan allows for the project (40 on Free, 200 on Pro, 1,000 on Scale). Retry with exponential backoff, spread requests out, or upgrade.
402: budget exceeded#
A spend limit was reached (project_budget_exceeded or workflow_budget_exceeded). Raise the cap, wait for the period to reset (UTC), or add a cheaper backup model. A 422 …_budget_config_error means the model has no price set for its spend limit.
502: provider error#
The AI provider failed. Check its status page, add backup models, and look at meta.attempts to see what happened at each step.
"Provider credentials not configured"#
Add the provider's key under Settings → Providers and check it shows as connected.