API reference
Error codes
Machine-readable API errors and retry guidance from the OpenAPI contract.
Every API error has status, a machine-readable message code and a human-readable
messageDetail. Branch on the code, not on the prose. Keep the X-Spavik-Request-Id
response header for diagnostics.
Retry policies
Honor Retry-After when provided, but check the policy before replaying a mutation.
A new idempotency key starts a new logical operation.
| Code | Guidance |
|---|---|
TOO_MANY_REQUESTS | Wait for Retry-After. Keep the same Idempotency-Key and payload if one was supplied. |
REQUEST_IN_PROGRESS | Retry with the same Idempotency-Key and payload after Retry-After. |
ENGINE_BUSY | For predictions and forecasts, wait for Retry-After and keep the original Idempotency-Key if supplied. Model creation or refresh may have completed: retry only with the original key and payload; REQUEST_INTERRUPTED requires inspection. Without an original key, inspect model mutations before retrying. |
ENGINE_UNAVAILABLE | The engine outcome may be unknown. Retry only with the original Idempotency-Key and payload; otherwise inspect the operation before retrying. |
USAGE_ACCOUNTING_UNAVAILABLE | Retry only with the original Idempotency-Key and payload; otherwise contact support before retrying. |
RATE_LIMIT_UNAVAILABLE | Retry after Retry-After; keep the same Idempotency-Key if supplied. |
REQUEST_LOG_UNAVAILABLE | Retry this GET after Retry-After. |
REQUEST_INTERRUPTED | The outcome is uncertain. Do not switch to a new key or retry automatically. Inspect the request log and contact support with x-spavik-request-id. |
IDEMPOTENCY_RESPONSE_UNAVAILABLE | The response could not be saved. Do not switch to a new key or retry automatically. Contact support with x-spavik-request-id. |
IDEMPOTENCY_KEY_REUSED | Use the original payload for a retry. Use a new key only for a deliberately new operation. |
CREDITS_EXHAUSTED | Buy credits or change plan before retrying. |
Integration error codes
These codes cover the documented API-key integrations, including shared authentication, validation and service failures. Not every code applies to every endpoint. Console sign-in, account administration and payment-management errors are excluded.
ACCOUNT_NOT_FOUNDADMIN_KEY_CANNOT_PREDICTAPI_KEY_EXPIREDAPI_KEY_INVALIDAUTH_REQUIREDBAD_REQUESTCOLUMN_MISMATCHCONTEXT_UNAVAILABLECREDITS_EXHAUSTEDCSV_UNREADABLEDATASET_TOO_LARGEDATA_KEK_INVALIDDATA_KEK_MISSINGDATA_KEY_MALFORMEDDATA_KEY_MISMATCHDATA_KEY_NOT_SENTDATA_KEY_UNREADABLEDATA_KEY_VERSION_UNKNOWNDATA_REQUIREDENGINE_BUSYENGINE_CATALOGUE_MISMATCHENGINE_ERRORENGINE_FAMILY_MISMATCHENGINE_FAMILY_ONLYENGINE_FAMILY_REQUIREDENGINE_MISMATCHENGINE_NO_MODELENGINE_PLAN_REQUIREDENGINE_RETIREDENGINE_UNAVAILABLEFILE_TOO_LARGEFORECAST_FAILEDHORIZON_REQUIREDIDEMPOTENCY_KEY_REUSEDIDEMPOTENCY_KEY_TOO_LONGIDEMPOTENCY_RESPONSE_UNAVAILABLEINPUT_REQUIREDINTERNAL_ERRORINVALID_DATEINVALID_ENGINE_VERSIONINVALID_INPUTINVALID_RANGEMALFORMED_PATHMODEL_ARCHIVEDMODEL_DELETEDMODEL_KEY_MISSINGMODEL_NOT_FOUNDMODEL_NOT_REFRESHABLEMODEL_NOT_TRAINEDNO_PENDING_OUTCOMESNO_ROWSOUTCOME_PREDICTION_INVALIDPERFORMANCE_UNAVAILABLEQUOTA_MODELS_EXCEEDEDRANGE_TOO_WIDERATE_LIMIT_UNAVAILABLEREFRESH_IN_PROGRESSREQUEST_INTERRUPTEDREQUEST_IN_PROGRESSREQUEST_LOG_UNAVAILABLEROUTE_NOT_FOUNDSCHEMA_MISMATCHTARGET_COLUMN_MISSINGTARGET_REQUIREDTARGET_TASK_FROZENTIMESTAMP_COLUMN_MISSINGTIMESTAMP_COLUMN_NOT_FOUNDTOO_MANY_REQUESTSTOO_MANY_ROWSUNKNOWN_ENGINE_VERSIONUNKNOWN_TASKUPLOAD_INVALIDUSAGE_ACCOUNTING_UNAVAILABLEUSAGE_UNAVAILABLEVALIDATION_ERRORVALIDATION_FAILEDWORKSPACE_NOT_FOUND
How is this guide?
Last updated on