Reference
Errors
Every failure has a stable code and a message that says how to fix it. No error is ever charged a credit.
Error body
REST and MCP errors share one shape. Validation errors add the path of each bad field.
{
"detail": {
"code": "INVALID_REQUEST",
"message": "positions[0]: holding quantity must be non-zero",
"errors": [{ "path": "positions[0]", "msg": "holding quantity must be non-zero" }]
}
}
Codes
| HTTP | Code | Meaning | Charged |
|---|---|---|---|
| 400 | KEY_IN_QUERY | key sent in the URL | No |
| 400 | INVALID_JSON | MCP body is not a JSON-RPC object | No |
| 401 | AUTHENTICATION_REQUIRED | missing or invalid key where one is needed | No |
| 403 | PLAN_REQUIRED | feature needs a higher plan; see required_plan | No |
| 404 | NOT_FOUND | no route at that path | No |
| 404 | KEY_NOT_FOUND | no such key on this account, or it is already revoked | No |
| 405 | METHOD_NOT_ALLOWED | wrong HTTP method for the route | No |
| 409 | BILLING_DISABLED | paid plans are not open yet; the free plan still works | No |
| 409 | ALREADY_SUBSCRIBED | this key already has a paid plan; use the billing portal | No |
| 409 | NO_BILLING_ACCOUNT | start a paid plan before managing billing | No |
| 409 | KEY_LIMIT | the account already has 10 active keys; revoke one first | No |
| 409 | LAST_KEY | the account's last active key; create or rotate before revoking | No |
| 410 | RECOVERY_LINK_INVALID | recovery link expired or already used | No |
| 422 | INVALID_REQUEST | body failed validation; see errors[].path | No |
| 422 | PRICES_REQUIRED | no history and not a demo ticker | No |
| 422 | POSITION_LIMIT | more tickers or positions than this caller's per-call limit | No |
| 422 | INSTRUMENT_NOT_ELIGIBLE_AT_TIME | no valuation close | No |
| 429 | RATE_LIMITED | daily limit used; Retry-After seconds until 00:00 UTC | No |
| 503 | DEPENDENCY_UNAVAILABLE | keys or database down | No |
| 503 | BILLING_PROVIDER_ERROR | the payment provider did not answer; retry later | No |
| 503 | RECOVERY_UNAVAILABLE | recovery email is not switched on yet | No |
Retries
- 429 RATE_LIMITED carries
Retry-After: the seconds until the daily limit resets at 00:00 UTC. - 503 errors are temporary. Retry with backoff.
- 4xx errors other than 429 fail the same way every time until the request changes.
Null values are not errors
A factor Creo cannot compute for a holding comes back null with a reason, inside
a successful response. See Missing data.