# Errors, pagination, and limits Handle InstantML API errors, page through large result sets, and stay inside request limits with the rules on this page. All routes accept the same credentials described in [API authentication](/docs/api/authentication.md). ## Error shape Every JSON error uses an HTTP status code and at least an `error` string. Try it by requesting a run that does not exist: ```bash curl -i https://api.instantml.ai/runs/00000000-0000-0000-0000-000000000000 \ -H "Authorization: Bearer instantml_..." ``` ```json { "error": "run not found" } ``` Some errors include a stable `code`: ```json { "error": "plan limit exceeded", "code": "plan_limit_exceeded" } ``` Most handlers also attach `x-request-id`. ## Common codes | Code | Meaning | | --- | --- | | `payment_required` | The org needs billing action before writes are accepted | | `plan_limit_exceeded` | The write would exceed a blocked plan limit | | `rate_limit_exceeded` | The request exceeded a short-window API rate limit | | `api_request_monthly_limit_exceeded` | The org reached a monthly API request allowance and does not have billable overage | | `warehouse_unavailable` | Hosted tenant warehouse is waking or unavailable | | `run_search_invalid` | The `q` run-search query has closed but invalid syntax | | `run_search_regex_unsupported` | Deprecated Node compatibility was asked to evaluate `re:/.../` | `warehouse_unavailable` uses HTTP `503` and is retryable from a client point of view. Run-search validation errors use HTTP `400` and include `field: "q"` plus an optional 1-based `position`: ```json { "error": "Invalid run search: regex is invalid at column 6.", "code": "run_search_invalid", "field": "q", "position": 6 } ``` ## Pagination and bounds Every list route returns a bounded page, never the full data set. Expect and handle these patterns: - `GET /runs` accepts `limit` and `offset`; pass a larger `offset` to fetch the next page instead of raising `limit` past its cap. - `GET /api/runs/summary` and `GET /api/runs/{run_id}/logs` return a `next_cursor` field; pass it back as `cursor` to fetch the next page. - Fetch metric series per run and key with `start_step`/`end_step` ranges and a point `limit`; batched series responses clamp the effective per-run limit so one response stays within the returned-point budget. - Artifact and object list responses cap their page size; narrow by run, kind, or key when you hit the cap. - Table row contents are not inlined in object envelopes; page them separately through `GET /api/objects/{object_id}/rows`. - When a response includes a `truncated` flag or truncation header, narrow the query before treating the result as complete. Common limits: | Input or route | Limit | | --- | ---: | | Text fields such as names, paths, and tags | 512 bytes | | Metrics per scalar batch | 1,000 | | Metric query limit | Default 1,000, max 5,000 | | Rank metrics per batch | 1,000 metrics for one `(run, step, rank)` | | Rank metric world size | 512 ranks | | Run page limit | Default 100, max 1,000 | | Run search query | 512 bytes, 32 terms, 64 AST nodes, depth 8 | | Run search regex | Max 4 regexes, 128 bytes each; regex must not match empty text | | Per-run searched field text | First 32 KiB per indexed field | | Batched metric series run IDs | 2,000 | | Batched metric series response | Max 120,000 returned points | | Workspace-view payload | 64 KiB | | Console log lines per batch | 50 | | Console log message | 16 KiB | | Console log query limit | Default 250, max 1,000 | | Object page limit | Default 100, max 500 | | Object table row limit | Default 100, max 1,000 | | Artifact list limit | Max 1,000 | | Side-by-side comparison | Max 50 runs and 5,000 rows | | Export runs | Max 500 filter-selected runs or 100 selected run IDs | | Export metric points | Max 100,000 rows | | Export metric series | Max 25,000 summaries | | Export attributes | Max 25,000 rows | | Export artifacts | Max 10,000 rows | | Export table rows | Max 25,000 rows | | Export import rows | Max 500 rows | | Export CSV response | Max 25 MiB | ## Ingest limits Metric ingest batches should stay within the API's documented batch size. High-frequency loops should batch several scalar values into one `run.log(...)` call instead of sending one request per scalar. Hosted short-window API rate limits are plan-aware: | Tier | General rate | Ingest rate | Monthly request allowance | | --- | ---: | ---: | ---: | | Free | 5 req/sec, burst 30 | 2 req/sec, burst 10 | 500k requests | | Pro | 50 req/sec, burst 250 | 25 req/sec, burst 125 | 25M requests | | Premium | 200 req/sec, burst 1000 | 100 req/sec, burst 500 | 150M requests | Short-window rate-limit responses use HTTP `429`, return `code: "rate_limit_exceeded"`, include `X-InstantML-RateLimit-Scope: second`, and set `Retry-After`, `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset`. Monthly quota responses use `code: "api_request_monthly_limit_exceeded"` with `X-InstantML-RateLimit-Scope: monthly` and reset at the next UTC calendar month. The Python SDK retries bounded short-window `429` responses internally and does not retry monthly quota failures. ## Idempotency Process-spool uploaders set `Idempotency-Key` for metric and console-log event replay. Compatible servers use that key to accept retries safely. ## Next steps - [Authenticate API calls](/docs/api/authentication.md) - [Query runs and summaries](/docs/api/projects-runs.md) - [Write and read metric series](/docs/api/metrics-series.md) - [Understand plan pricing and limits](/docs/guides/pricing-limits-billing.md) - [Build reliable high-volume logging](/docs/sdk/reliability.md) ## Agent navigation - [Docs index](/llms.txt) - [Full docs bundle](/llms-full.txt) ### Get Started - [Overview](/docs/index.md) - [Quickstart](/docs/quickstart.md) - [Core Concepts](/docs/concepts/core-concepts.md) - [Pricing](/docs/pricing.md) - [Benchmarks](/docs/benchmarks.md) - [Examples](/docs/guides/examples.md) - [Troubleshooting](/docs/troubleshooting.md) ### SDK - [Installation Auth](/docs/sdk/installation-auth.md) - [Logging](/docs/sdk/logging.md) - [Tracing](/docs/sdk/tracing.md) - [Metrics Steps](/docs/sdk/metrics-steps.md) - [Config Tags Notes](/docs/sdk/config-tags-notes.md) - [Artifacts Checkpoints](/docs/sdk/artifacts-checkpoints.md) - [Rich Objects](/docs/sdk/rich-objects.md) - [Distributed Training](/docs/sdk/distributed-training.md) - [Console System Integrations](/docs/sdk/console-system-integrations.md) - [Reliability](/docs/sdk/reliability.md) - [Cli Login](/docs/sdk/cli-login.md) - [Querying Data](/docs/sdk/querying-data.md) - [Agent Mcp](/docs/sdk/agent-mcp.md) - [Examples Patterns](/docs/sdk/examples-patterns.md) ### Integrations - [Overview](/docs/integrations/overview.md) - [Pytorch Lightning](/docs/integrations/pytorch-lightning.md) - [Huggingface Transformers](/docs/integrations/huggingface-transformers.md) - [Keras](/docs/integrations/keras.md) - [Wandb](/docs/integrations/wandb.md) ### Dashboard - [Tour](/docs/dashboard/tour.md) - [Organizations Workspaces](/docs/dashboard/organizations-workspaces.md) - [Runs Workspace](/docs/dashboard/runs-workspace.md) - [Metrics Charts](/docs/dashboard/metrics-charts.md) - [Run Detail](/docs/dashboard/run-detail.md) - [Traces](/docs/dashboard/traces.md) - [Compare Runs](/docs/dashboard/compare-runs.md) - [Research Dashboards](/docs/dashboard/research-dashboards.md) - [Artifacts Files](/docs/dashboard/artifacts-files.md) - [Run Health](/docs/dashboard/alerts.md) - [Datasets](/docs/dashboard/datasets.md) - [Checkpoints](/docs/dashboard/checkpoints.md) - [Reports](/docs/dashboard/reports.md) - [Settings Api Keys](/docs/dashboard/settings-api-keys.md) - [Api Tab](/docs/dashboard/api-tab.md) - [Onboarding Team Billing](/docs/dashboard/onboarding-team-billing.md) ### Data - [Imports](/docs/guides/imports.md) - [W&B alternative](/docs/guides/wandb-alternative.md) - [InstantML vs MLflow](/docs/guides/instantml-vs-mlflow.md) - [W&B import guide](/docs/guides/wandb-import-guide.md) - [W&B and Neptune imports](/docs/guides/wandb-neptune-imports.md) - [Export Usage Limits](/docs/guides/export-usage-limits.md) - [Pricing Limits Billing](/docs/guides/pricing-limits-billing.md) - [Auth Billing Storage](/docs/guides/auth-billing-storage.md) - [Customer Owned Clickhouse](/docs/guides/customer-owned-clickhouse.md) - [Observability](/docs/guides/observability.md) ### API **Practical API guides** - [Authentication](/docs/api/authentication.md) - [Errors And Limits](/docs/api/errors-and-limits.md) (current page) - [Health Observability](/docs/api/health-observability.md) - [Projects Runs](/docs/api/projects-runs.md) - [Metrics Series](/docs/api/metrics-series.md) - [Attributes Objects](/docs/api/attributes-objects.md) - [Artifacts](/docs/api/artifacts.md) - [Reports](/docs/api/reports.md) - [Iframe Embeds](/docs/api/iframe-embeds.md) - [Import Export Usage](/docs/api/import-export-usage.md) - [Dashboard Control State](/docs/api/dashboard-control-state.md) **Architecture** - [System Overview](/docs/architecture/system-overview.md) - [Service Planes](/docs/architecture/service-planes.md) - [Storage Model](/docs/architecture/storage-model.md) - [Google Clickhouse](/docs/architecture/google-clickhouse.md) - [Auth Tenancy](/docs/architecture/auth-tenancy.md) - [Schema Reference](/docs/architecture/schema-reference.md) ### API Reference - [API Reference](/docs/api-reference.md)