roasOSErrors
The structure of an error response, and what to do with it.
All errors have the same structure. Your software can therefore process all errors in the same way.
{
"error": {
"code": "invalid_api_key",
"message": "Invalid or revoked API key",
"retryable": false,
"request_id": "7501d15d-b189-40ea-b8fa-629cf4722618"
}
}The fields
code— a stable code for your software. Use this field in your conditions. Do not use themessagefield.message— an explanation for a person. The text can change. Do not parse the text.retryable— the valuetrueshows that the same request can be successful later. The valuefalseshows that you must first correct the request.request_id— the identifier of the request. Give this identifier to the support staff.
HTTP status codes
| Status | Meaning |
|---|---|
400 | The request contains data that is not valid. |
401 | The API key is absent or not valid. |
402 | Your workspace does not have sufficient credits. |
403 | Your key does not have permission for this action, or the price is above a spend bound. |
404 | roasOS cannot find the item in your workspace. |
409 | The item exists, and its state refuses this action. |
410 | The quote expired. Quote the request again. |
429 | You sent too many requests. Decrease the rate. |
5xx | An internal error occurred. Send the request again if retryable is true. |
Codes on a paid request
These codes belong to the quote and confirm flow. Refer to Quotes and credits.
| Code | Status | Cause |
|---|---|---|
idempotency_key_required | 400 | The Idempotency-Key header is absent. |
invalid_idempotency_key | 400 | The header value is not 16 to 255 characters of the allowed set. |
quote_required | 400 | The body carries no quote_only and no quote_id. |
quote_expired | 410 | More than 10 minutes passed since the quote. |
insufficient_credits | 402 | The workspace balance is below the price. |
request_credit_limit_exceeded | 403 | The price is above max_credits_per_request on your key. |
daily_credit_budget_exceeded | 403 | The daily budget of the key is used. |
monthly_credit_budget_exceeded | 403 | The monthly budget of the key is used. |
spend_approval_required | 403 | The price is above the approval threshold, and no person approved it. |
rate_limit_exceeded | 429 | The key sent too many requests. |
409 — the state refuses the action
A 409 is a state answer, and it is never a fault in your body. Three are common.
| Code | Cause | What to do |
|---|---|---|
run_not_completed | You read /result before the job is terminal. | Poll /status first. Refer to Jobs. |
job_not_cancelable | You canceled a job that is already terminal. | Read the job. It finished. |
research_result_not_ready | You read a research result before the job is terminal. | Poll the status of the research job. |
503 — a store that cannot answer
The quotes, the memory, the brand kit, the intelligence, the skills and the idempotency records each have their own store. When one store cannot answer, the request stops with a 503, and the code names the store. This is a published shape, and it is not a fault in your request.
The retryable field splits the family in two. Read it, and do not assume that a 503 is always transient.
retryable | Codes |
|---|---|
true | idempotency_store_unavailable, generation_quote_store_unavailable, research_quote_store_unavailable |
false | brand_kit_store_unavailable, memory_store_unavailable, intelligence_store_unavailable, skill_store_unavailable, generation_batch_quote_store_unavailable, media_rights_attestation_store_unavailable, billing_command_store_unavailable |
A 503 with retryable: false means that roasOS cannot prove what the request did. Read the state before you send the request again. Send it with the same Idempotency-Key, so a paid action that did run charges you one time only.
Send a request again safely
If retryable is true, send the request again with the same Idempotency-Key. roasOS then charges you one time only.
Increase the delay between the attempts. For example, wait 1 second, then 2 seconds, then 4 seconds.
A paid request can stop with a timeout. You then do not know if the action ran. Send the request again with the same key. If the action ran, roasOS gives you the first result. If the action did not run, roasOS runs it.