Troubleshooting errors

When a request is malformed or fails to process, the server returns an error in JSON form. Don't panic — most errors have a clear cause and can be fixed quickly.

Every error includes a code (error code). Just by looking at this code, you can tell right away "what the problem is."

What an error looks like

{
  "error": {
    "code": "invalid_api_key",
    "message": "A human-readable explanation message",
    "type": "modoo_error"
  }
}

code — the type of problem (look it up in the table below).
message — an explanation of what went wrong.
type — always modoo_error (a marker that this error came from this API).

The first place to look

When a problem occurs, check the code first. Find the same code in the table and explanations below and follow the steps exactly.

Errors at a glance

code	HTTP	Meaning	Fix
`missing_api_key`	401	No key header	Add the `Authorization` header
`invalid_api_key`	401	Key is wrong or inactive	Check/reissue the key in the dashboard
`insufficient_credits`	402	Credits used up	Top up your credits (check your subscription)
`model_not_found`	404	Typo in the model name	Confirm the exact name with `GET /v1/models`
`not_found`	404	Nonexistent job/run id	Check the `job_id`/`run_id`
`no_backend_account`	409	AI usage settings not yet connected to the account	Check your subscription/settings (contact support)
`invalid_request`	422	Malformed request	Check that you included `messages` or `prompt`
`invalid_workflow`	400	Incompatible block connection	Fix the connection as the error message suggests
`rate_limited`	429	Too many calls	Try again shortly
`daily_quota_exceeded`	429	Daily usage limit reached	Try again tomorrow or raise the limit
`upstream_error`	502	Temporary processing error	Try again shortly

Authentication & credit problems (401 / 402)

These are problems with the key (API key) that confirms "who you are," or with the credits needed to use the service.

missing_api_key

What does it mean? It means you didn't include the API key (which acts as your ID) in the request at all.

Why does it happen? You left out the Authorization header when sending the request.

How do I fix it?

Include the header below in every request.

Authorization: Bearer sk-modoo-...

In place of sk-modoo-..., put the actual key you issued from the dashboard.

{ "error": { "code": "missing_api_key", "message": "The Authorization header is missing.", "type": "modoo_error" } }

invalid_api_key

What does it mean? It means you did include a key, but that key is wrong or can no longer be used (inactive).

Why does it happen? Often part of the key was left out when copying it, or you used an old, deactivated key.

How do I fix it?

Copy the key from the dashboard again and paste it exactly (watch for leading/trailing spaces).
If it still doesn't work, reissue the key in the dashboard and use the new key.

{ "error": { "code": "invalid_api_key", "message": "The key is invalid or inactive.", "type": "modoo_error" } }

insufficient_credits

What does it mean? It means you don't have enough remaining credits to process this request. Credits are deducted little by little each time you use the AI.

Why does it happen? You used up your credits due to heavy usage, or your subscription expired.

How do I fix it?

Check your remaining credits with GET /v1/credits.

curl https://modoo.devdive.me/v1/credits \
 -H "Authorization: Bearer sk-modoo-..."

If your credits are near 0, top up or check your subscription status in the dashboard.

{ "error": { "code": "insufficient_credits", "message": "Insufficient credits.", "type": "modoo_error" } }

If you keep running low on credits

Switching to cheaper models (modoo-text-mini, modoo-text-nano) can save credits. For model selection, see the Models guide.

Request problems (400 / 404 / 422)

These appear when there's a typo or formatting problem in the request itself. Just tweak what you sent a little.

model_not_found

What does it mean? It means the requested model name can't be found. Most often it's a typo.

Why does it happen? You wrote modoo-text-pro as modoo-textpro, or used a name that doesn't exist.

How do I fix it?

Confirm the exact model name with GET /v1/models.

curl https://modoo.devdive.me/v1/models \
 -H "Authorization: Bearer sk-modoo-..."

Copy the id value from the response exactly and put it in model.

{ "error": { "code": "model_not_found", "message": "That model could not be found.", "type": "modoo_error" } }

not_found

What does it mean? It means the job (job_id) or workflow run (run_id) you're looking up doesn't exist.

Why does it happen? There's a typo in the number, or you looked up someone else's job number (one that isn't yours).

How do I fix it?

Check that you copied the job_id / run_id you received when you submitted the task exactly.
Check that the lookup address matches the GET /v1/jobs/{job_id} format (for how to poll, see the API Reference).

{ "error": { "code": "not_found", "message": "That job could not be found.", "type": "modoo_error" } }

invalid_request

What does it mean? It means the request format is wrong. It's very likely that a required value is missing.

Why does it happen? In a text request you included neither messages nor prompt, or you left out a required item.

How do I fix it?

For a text request, you must include one of messages or prompt.
Double-check that the item names and format match the examples (see Model examples).

{ "error": { "code": "invalid_request", "message": "messages or prompt is required.", "type": "modoo_error" } }

invalid_workflow

What does it mean? It means that the connections in a workflow — several AI tasks chained together — don't line up with each other.

Why does it happen? You referenced a block that hasn't run yet (one that comes later), tried to pull an output field that doesn't exist, or wired a result of a mismatched kind into the next block's input.

How do I fix it?

The error message kindly points out which connection is the problem, so fix it as described.
Order things so that later blocks only reference the results of earlier blocks.
For detailed connection rules, see the Workflows guide.

{ "error": { "code": "invalid_workflow", "message": "Cannot reference the later block 'draft'.", "type": "modoo_error" } }

Workflows are checked before they run

If a connection doesn't line up, we let you know in advance with this error before it actually runs. Thanks to that, you don't waste credits.

no_backend_account

What does it mean? It means the AI usage settings aren't yet connected to your account. (HTTP 409)

Why does it happen? You have a subscription, but the initial setup for using the AI isn't finished yet.

How do I fix it?

Check in the dashboard that your subscription and usage settings are in order.
If your settings are fine but it keeps appearing, contact support.

{ "error": { "code": "no_backend_account", "message": "AI usage settings are not yet connected.", "type": "modoo_error" } }

Limit problems (429)

If you use too much at once, a brief limit is applied to keep the service stable. This isn't a problem — it's a normal safeguard.

rate_limited

What does it mean? It means you sent too many requests in a short time.

Why does it happen? You exceeded the number of calls allowed per minute (the rate limit).

How do I fix it?

Wait a moment (a few seconds to a minute) and try again.
If you make many repeated requests, put a little gap between them.
For per-model limits, see the Call limits table in the Models guide.

{ "error": { "code": "rate_limited", "message": "Too many requests. Please try again shortly.", "type": "modoo_error" } }

daily_quota_exceeded

What does it mean? It means you've reached the usage limit available for one day.

Why does it happen? You used up all of the usage limit set for that day.

How do I fix it?

The next day, once the limit resets, you can use it again.
If you need to use more, request a limit increase through the dashboard or support.

{ "error": { "code": "daily_quota_exceeded", "message": "You've reached the daily usage limit.", "type": "modoo_error" } }

⏳ Temporary errors (502)

There's nothing wrong with your request, but a brief problem occurred during processing. Most of the time, trying again resolves it.

upstream_error

What does it mean? It means a temporary error occurred during AI processing.

Why does it happen? A momentary load spike or temporary outage — usually a problem that passes quickly.

How do I fix it?

Send the same request again after a short while. It usually succeeds after one or two retries.
If it keeps happening, wait a little longer before trying, or contact support.

{ "error": { "code": "upstream_error", "message": "A temporary processing error occurred. Please try again shortly.", "type": "modoo_error" } }

A tip for retrying

When repeating the same request, gradually increasing the interval (for example, 1s → 3s → 10s) improves your chances of success.

If it still isn't resolved

First, re-check your basic setup (key, header) with the Quickstart.
You can confirm the exact request format in the API Reference.
If the same error keeps recurring, contact support with the error's code and message together. It'll help find the cause much faster.

What an error looks like​

Errors at a glance​

Authentication & credit problems (401 / 402)​

missing_api_key​

invalid_api_key​

insufficient_credits​

Request problems (400 / 404 / 422)​

model_not_found​

not_found​

invalid_request​

invalid_workflow​

no_backend_account​

Limit problems (429)​

rate_limited​

daily_quota_exceeded​

⏳ Temporary errors (502)​

upstream_error​

If it still isn't resolved​

What an error looks like

Errors at a glance

Authentication & credit problems (401 / 402)

missing_api_key

invalid_api_key

insufficient_credits

Request problems (400 / 404 / 422)

model_not_found

not_found

invalid_request

invalid_workflow

no_backend_account

Limit problems (429)

rate_limited

daily_quota_exceeded

⏳ Temporary errors (502)

upstream_error

If it still isn't resolved