Run a batch
POST /api/v1/batch — run up to 100 Ostra Decision tasks in one request, mixed tasks allowed, at half the price.
https://ostra.testrelic.ai/api/v1/batchRuns up to 100 Ostra Decision tasks in one request, mixed tasks allowed, at half the price.
Each item is answered independently: one bad item fails on its own and the rest still answer. Results come back in input order, with your custom_id. Items run 8 at a time with a 25-second deadline for the whole batch; items that don’t start in time fail with upstream_timeout and are refunded.
- Auth
Authorization: Bearer $OSTRA_API_KEY. Needs a Full-access key.- Rate limit
- Counts against your workspace's requests per minute.
- Cost
- Each item costs half its
/predictprice (rounded up to the nano-dollar). Failed and cached items are free. If the balance can’t cover the whole batch, the whole batch is refused with 402.
curl https://ostra.testrelic.ai/api/v1/batch \
-H "Authorization: Bearer $OSTRA_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "ostra-lite",
"items": [
{
"custom_id": "checkout-applies-coupon",
"task": "triage",
"input": {
"test_id": "checkout.spec.ts > applies coupon",
"run_id": "gha-18241",
"context": {
"framework": "playwright",
"capture_level": "full",
"error_message": "TimeoutError: locator.click: Timeout 30000ms exceeded.\n waiting for locator('\''#apply-coupon'\'')",
"action": "click",
"locator": {
"strategy": "css"
},
"diff": {
"files_changed": 3,
"lines_added": 41,
"lines_removed": 12,
"touches_test_file": false,
"touches_selector_file": false,
"locator_values_removed": false
},
"dom": {
"locator_found": true
},
"memory": {
"runs_50": 40,
"flake_rate_50": 0.15,
"failed_count_50": 6,
"signature_repeat_count": 5
}
}
}
},
{
"custom_id": "orders-lists-orders",
"task": "triage",
"input": {
"test_id": "orders.api.spec.ts > lists orders",
"context": {
"framework": "jest",
"error_message": "Error: Request failed with status code 503 (Service Unavailable) GET /api/orders",
"action": "api_call"
}
}
},
{
"custom_id": "coupon-locators",
"task": "selector_survival",
"input": {
"locators": [
{
"locator_id": "checkout.apply-coupon",
"strategy": "css",
"dom_locator_found": true,
"history": [
{
"release": "2026.10.1",
"resolve_rate": 1
},
{
"release": "2026.10.2",
"resolve_rate": 0.92
},
{
"release": "2026.11.1",
"resolve_rate": 0.71
}
]
},
{
"locator_id": "nav.account-menu",
"strategy": "role",
"dom_locator_found": true,
"history": [
{
"release": "2026.10.2",
"resolve_rate": 1
},
{
"release": "2026.11.1",
"resolve_rate": 1
}
]
}
]
}
}
]
}'import os
import requests
response = requests.post(
"https://ostra.testrelic.ai/api/v1/batch",
headers={
"Authorization": f"Bearer {os.environ['OSTRA_API_KEY']}",
},
json={
"model": "ostra-lite",
"items": [
{
"custom_id": "checkout-applies-coupon",
"task": "triage",
"input": {
"test_id": "checkout.spec.ts > applies coupon",
"run_id": "gha-18241",
"context": {
"framework": "playwright",
"capture_level": "full",
"error_message": "TimeoutError: locator.click: Timeout 30000ms exceeded.\n waiting for locator('#apply-coupon')",
"action": "click",
"locator": {
"strategy": "css",
},
"diff": {
"files_changed": 3,
"lines_added": 41,
"lines_removed": 12,
"touches_test_file": False,
"touches_selector_file": False,
"locator_values_removed": False,
},
"dom": {
"locator_found": True,
},
"memory": {
"runs_50": 40,
"flake_rate_50": 0.15,
"failed_count_50": 6,
"signature_repeat_count": 5,
},
},
},
},
{
"custom_id": "orders-lists-orders",
"task": "triage",
"input": {
"test_id": "orders.api.spec.ts > lists orders",
"context": {
"framework": "jest",
"error_message": "Error: Request failed with status code 503 (Service Unavailable) GET /api/orders",
"action": "api_call",
},
},
},
{
"custom_id": "coupon-locators",
"task": "selector_survival",
"input": {
"locators": [
{
"locator_id": "checkout.apply-coupon",
"strategy": "css",
"dom_locator_found": True,
"history": [
{
"release": "2026.10.1",
"resolve_rate": 1,
},
{
"release": "2026.10.2",
"resolve_rate": 0.92,
},
{
"release": "2026.11.1",
"resolve_rate": 0.71,
},
],
},
{
"locator_id": "nav.account-menu",
"strategy": "role",
"dom_locator_found": True,
"history": [
{
"release": "2026.10.2",
"resolve_rate": 1,
},
{
"release": "2026.11.1",
"resolve_rate": 1,
},
],
},
],
},
},
],
},
timeout=60,
)
response.raise_for_status()
print(response.json())const response = await fetch('https://ostra.testrelic.ai/api/v1/batch', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.OSTRA_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
model: 'ostra-lite',
items: [
{
custom_id: 'checkout-applies-coupon',
task: 'triage',
input: {
test_id: 'checkout.spec.ts > applies coupon',
run_id: 'gha-18241',
context: {
framework: 'playwright',
capture_level: 'full',
error_message: 'TimeoutError: locator.click: Timeout 30000ms exceeded.\n waiting for locator(\'#apply-coupon\')',
action: 'click',
locator: {
strategy: 'css',
},
diff: {
files_changed: 3,
lines_added: 41,
lines_removed: 12,
touches_test_file: false,
touches_selector_file: false,
locator_values_removed: false,
},
dom: {
locator_found: true,
},
memory: {
runs_50: 40,
flake_rate_50: 0.15,
failed_count_50: 6,
signature_repeat_count: 5,
},
},
},
},
{
custom_id: 'orders-lists-orders',
task: 'triage',
input: {
test_id: 'orders.api.spec.ts > lists orders',
context: {
framework: 'jest',
error_message: 'Error: Request failed with status code 503 (Service Unavailable) GET /api/orders',
action: 'api_call',
},
},
},
{
custom_id: 'coupon-locators',
task: 'selector_survival',
input: {
locators: [
{
locator_id: 'checkout.apply-coupon',
strategy: 'css',
dom_locator_found: true,
history: [
{
release: '2026.10.1',
resolve_rate: 1,
},
{
release: '2026.10.2',
resolve_rate: 0.92,
},
{
release: '2026.11.1',
resolve_rate: 0.71,
},
],
},
{
locator_id: 'nav.account-menu',
strategy: 'role',
dom_locator_found: true,
history: [
{
release: '2026.10.2',
resolve_rate: 1,
},
{
release: '2026.11.1',
resolve_rate: 1,
},
],
},
],
},
},
],
}),
});
if (!response.ok) {
throw new Error(`Ostra ${response.status}: ${await response.text()}`);
}
console.log(await response.json());package main
import (
"fmt"
"io"
"net/http"
"os"
"strings"
)
func main() {
body := strings.NewReader(`{
"model": "ostra-lite",
"items": [
{
"custom_id": "checkout-applies-coupon",
"task": "triage",
"input": {
"test_id": "checkout.spec.ts > applies coupon",
"run_id": "gha-18241",
"context": {
"framework": "playwright",
"capture_level": "full",
"error_message": "TimeoutError: locator.click: Timeout 30000ms exceeded.\n waiting for locator('#apply-coupon')",
"action": "click",
"locator": {
"strategy": "css"
},
"diff": {
"files_changed": 3,
"lines_added": 41,
"lines_removed": 12,
"touches_test_file": false,
"touches_selector_file": false,
"locator_values_removed": false
},
"dom": {
"locator_found": true
},
"memory": {
"runs_50": 40,
"flake_rate_50": 0.15,
"failed_count_50": 6,
"signature_repeat_count": 5
}
}
}
},
{
"custom_id": "orders-lists-orders",
"task": "triage",
"input": {
"test_id": "orders.api.spec.ts > lists orders",
"context": {
"framework": "jest",
"error_message": "Error: Request failed with status code 503 (Service Unavailable) GET /api/orders",
"action": "api_call"
}
}
},
{
"custom_id": "coupon-locators",
"task": "selector_survival",
"input": {
"locators": [
{
"locator_id": "checkout.apply-coupon",
"strategy": "css",
"dom_locator_found": true,
"history": [
{
"release": "2026.10.1",
"resolve_rate": 1
},
{
"release": "2026.10.2",
"resolve_rate": 0.92
},
{
"release": "2026.11.1",
"resolve_rate": 0.71
}
]
},
{
"locator_id": "nav.account-menu",
"strategy": "role",
"dom_locator_found": true,
"history": [
{
"release": "2026.10.2",
"resolve_rate": 1
},
{
"release": "2026.11.1",
"resolve_rate": 1
}
]
}
]
}
}
]
}`)
req, err := http.NewRequest("POST", "https://ostra.testrelic.ai/api/v1/batch", body)
if err != nil {
panic(err)
}
req.Header.Set("Authorization", "Bearer "+os.Getenv("OSTRA_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
out, err := io.ReadAll(res.Body)
if err != nil {
panic(err)
}
fmt.Println(res.Status)
fmt.Println(string(out))
}import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class OstraExample {
public static void main(String[] args) throws Exception {
String body = """
{
"model": "ostra-lite",
"items": [
{
"custom_id": "checkout-applies-coupon",
"task": "triage",
"input": {
"test_id": "checkout.spec.ts > applies coupon",
"run_id": "gha-18241",
"context": {
"framework": "playwright",
"capture_level": "full",
"error_message": "TimeoutError: locator.click: Timeout 30000ms exceeded.\\n waiting for locator('#apply-coupon')",
"action": "click",
"locator": {
"strategy": "css"
},
"diff": {
"files_changed": 3,
"lines_added": 41,
"lines_removed": 12,
"touches_test_file": false,
"touches_selector_file": false,
"locator_values_removed": false
},
"dom": {
"locator_found": true
},
"memory": {
"runs_50": 40,
"flake_rate_50": 0.15,
"failed_count_50": 6,
"signature_repeat_count": 5
}
}
}
},
{
"custom_id": "orders-lists-orders",
"task": "triage",
"input": {
"test_id": "orders.api.spec.ts > lists orders",
"context": {
"framework": "jest",
"error_message": "Error: Request failed with status code 503 (Service Unavailable) GET /api/orders",
"action": "api_call"
}
}
},
{
"custom_id": "coupon-locators",
"task": "selector_survival",
"input": {
"locators": [
{
"locator_id": "checkout.apply-coupon",
"strategy": "css",
"dom_locator_found": true,
"history": [
{
"release": "2026.10.1",
"resolve_rate": 1
},
{
"release": "2026.10.2",
"resolve_rate": 0.92
},
{
"release": "2026.11.1",
"resolve_rate": 0.71
}
]
},
{
"locator_id": "nav.account-menu",
"strategy": "role",
"dom_locator_found": true,
"history": [
{
"release": "2026.10.2",
"resolve_rate": 1
},
{
"release": "2026.11.1",
"resolve_rate": 1
}
]
}
]
}
}
]
}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://ostra.testrelic.ai/api/v1/batch"))
.header("Authorization", "Bearer " + System.getenv("OSTRA_API_KEY"))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(body))
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());
System.out.println(response.body());
}
}using System.Net.Http.Headers;
using System.Text;
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("OSTRA_API_KEY"));
using var request = new HttpRequestMessage(HttpMethod.Post, "https://ostra.testrelic.ai/api/v1/batch");
request.Content = new StringContent(
"""
{
"model": "ostra-lite",
"items": [
{
"custom_id": "checkout-applies-coupon",
"task": "triage",
"input": {
"test_id": "checkout.spec.ts > applies coupon",
"run_id": "gha-18241",
"context": {
"framework": "playwright",
"capture_level": "full",
"error_message": "TimeoutError: locator.click: Timeout 30000ms exceeded.\n waiting for locator('#apply-coupon')",
"action": "click",
"locator": {
"strategy": "css"
},
"diff": {
"files_changed": 3,
"lines_added": 41,
"lines_removed": 12,
"touches_test_file": false,
"touches_selector_file": false,
"locator_values_removed": false
},
"dom": {
"locator_found": true
},
"memory": {
"runs_50": 40,
"flake_rate_50": 0.15,
"failed_count_50": 6,
"signature_repeat_count": 5
}
}
}
},
{
"custom_id": "orders-lists-orders",
"task": "triage",
"input": {
"test_id": "orders.api.spec.ts > lists orders",
"context": {
"framework": "jest",
"error_message": "Error: Request failed with status code 503 (Service Unavailable) GET /api/orders",
"action": "api_call"
}
}
},
{
"custom_id": "coupon-locators",
"task": "selector_survival",
"input": {
"locators": [
{
"locator_id": "checkout.apply-coupon",
"strategy": "css",
"dom_locator_found": true,
"history": [
{
"release": "2026.10.1",
"resolve_rate": 1
},
{
"release": "2026.10.2",
"resolve_rate": 0.92
},
{
"release": "2026.11.1",
"resolve_rate": 0.71
}
]
},
{
"locator_id": "nav.account-menu",
"strategy": "role",
"dom_locator_found": true,
"history": [
{
"release": "2026.10.2",
"resolve_rate": 1
},
{
"release": "2026.11.1",
"resolve_rate": 1
}
]
}
]
}
}
]
}
""",
Encoding.UTF8,
"application/json");
using var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());require "net/http"
require "uri"
uri = URI("https://ostra.testrelic.ai/api/v1/batch")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("OSTRA_API_KEY")}"
request["Content-Type"] = "application/json"
request.body = <<~'JSON'
{
"model": "ostra-lite",
"items": [
{
"custom_id": "checkout-applies-coupon",
"task": "triage",
"input": {
"test_id": "checkout.spec.ts > applies coupon",
"run_id": "gha-18241",
"context": {
"framework": "playwright",
"capture_level": "full",
"error_message": "TimeoutError: locator.click: Timeout 30000ms exceeded.\n waiting for locator('#apply-coupon')",
"action": "click",
"locator": {
"strategy": "css"
},
"diff": {
"files_changed": 3,
"lines_added": 41,
"lines_removed": 12,
"touches_test_file": false,
"touches_selector_file": false,
"locator_values_removed": false
},
"dom": {
"locator_found": true
},
"memory": {
"runs_50": 40,
"flake_rate_50": 0.15,
"failed_count_50": 6,
"signature_repeat_count": 5
}
}
}
},
{
"custom_id": "orders-lists-orders",
"task": "triage",
"input": {
"test_id": "orders.api.spec.ts > lists orders",
"context": {
"framework": "jest",
"error_message": "Error: Request failed with status code 503 (Service Unavailable) GET /api/orders",
"action": "api_call"
}
}
},
{
"custom_id": "coupon-locators",
"task": "selector_survival",
"input": {
"locators": [
{
"locator_id": "checkout.apply-coupon",
"strategy": "css",
"dom_locator_found": true,
"history": [
{
"release": "2026.10.1",
"resolve_rate": 1
},
{
"release": "2026.10.2",
"resolve_rate": 0.92
},
{
"release": "2026.11.1",
"resolve_rate": 0.71
}
]
},
{
"locator_id": "nav.account-menu",
"strategy": "role",
"dom_locator_found": true,
"history": [
{
"release": "2026.10.2",
"resolve_rate": 1
},
{
"release": "2026.11.1",
"resolve_rate": 1
}
]
}
]
}
}
]
}
JSON
response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
puts response.code
puts response.body<?php
$ch = curl_init("https://ostra.testrelic.ai/api/v1/batch");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer " . getenv("OSTRA_API_KEY"),
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => <<<'JSON'
{
"model": "ostra-lite",
"items": [
{
"custom_id": "checkout-applies-coupon",
"task": "triage",
"input": {
"test_id": "checkout.spec.ts > applies coupon",
"run_id": "gha-18241",
"context": {
"framework": "playwright",
"capture_level": "full",
"error_message": "TimeoutError: locator.click: Timeout 30000ms exceeded.\n waiting for locator('#apply-coupon')",
"action": "click",
"locator": {
"strategy": "css"
},
"diff": {
"files_changed": 3,
"lines_added": 41,
"lines_removed": 12,
"touches_test_file": false,
"touches_selector_file": false,
"locator_values_removed": false
},
"dom": {
"locator_found": true
},
"memory": {
"runs_50": 40,
"flake_rate_50": 0.15,
"failed_count_50": 6,
"signature_repeat_count": 5
}
}
}
},
{
"custom_id": "orders-lists-orders",
"task": "triage",
"input": {
"test_id": "orders.api.spec.ts > lists orders",
"context": {
"framework": "jest",
"error_message": "Error: Request failed with status code 503 (Service Unavailable) GET /api/orders",
"action": "api_call"
}
}
},
{
"custom_id": "coupon-locators",
"task": "selector_survival",
"input": {
"locators": [
{
"locator_id": "checkout.apply-coupon",
"strategy": "css",
"dom_locator_found": true,
"history": [
{
"release": "2026.10.1",
"resolve_rate": 1
},
{
"release": "2026.10.2",
"resolve_rate": 0.92
},
{
"release": "2026.11.1",
"resolve_rate": 0.71
}
]
},
{
"locator_id": "nav.account-menu",
"strategy": "role",
"dom_locator_found": true,
"history": [
{
"release": "2026.10.2",
"resolve_rate": 1
},
{
"release": "2026.11.1",
"resolve_rate": 1
}
]
}
]
}
}
]
}
JSON,
]);
$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
echo $response, PHP_EOL;Headers
- x-request-id
- req_01JDXK4M7Q2N8R5T6V9W3Y1Z0A
- ostra-ratelimit-requests-limit
- 600
- ostra-ratelimit-requests-remaining
- 597
- ostra-ratelimit-requests-reset
- 42
- ostra-balance-remaining-usd
- 24.99999875
{
"id": "req_01JDXK7Z8Y7X6W5V4U3T2S1R0Q",
"model": "ostra-lite@v.beta.5",
"billed": {
"units": 4,
"costNano": 750,
"costUsd": "0.00000075"
},
"results": [
{
"custom_id": "checkout-applies-coupon",
"ok": true,
"task": "triage",
"cached": false,
"output": {
"decision_id": "dec_5b0c9e2a7f3d4e18a6b2c9d0e1f4a7b3",
"task": "triage",
"decision": "flaky",
"value": "flaky",
"p": 0.83,
"probabilities": {
"flaky": 0.83,
"product_bug": 0.06,
"test_bug": 0.05,
"environment": 0.04,
"selector_drift": 0.02
},
"threshold": 0.6,
"defer_reason": null,
"decided_by": "model",
"rule": null,
"model": {
"release": "v.beta.5",
"version": "1.4.0",
"content_hash": "sha256:3f9a1c07d2e4b8a6",
"gate_passed": true
},
"test_id": "checkout.spec.ts > applies coupon",
"run_id": "gha-18241",
"error_class": "timeout",
"error_class_source": "error_message"
}
},
{
"custom_id": "orders-lists-orders",
"ok": true,
"task": "triage",
"cached": false,
"output": {
"decision_id": "dec_6f708192a3b4c5d6e7f8091a2b3c4d5e",
"task": "triage",
"decision": "environment",
"value": "environment",
"p": 0.74,
"probabilities": {
"flaky": 0.12,
"product_bug": 0.08,
"test_bug": 0.03,
"environment": 0.74,
"selector_drift": 0.03
},
"threshold": 0.6,
"defer_reason": null,
"decided_by": "model",
"rule": null,
"model": {
"release": "v.beta.5",
"version": "1.4.0",
"content_hash": "sha256:3f9a1c07d2e4b8a6",
"gate_passed": true
},
"test_id": "orders.api.spec.ts > lists orders",
"run_id": null,
"error_class": "network_error",
"error_class_source": "error_message"
}
},
{
"custom_id": "coupon-locators",
"ok": true,
"task": "selector_survival",
"cached": false,
"output": {
"decisions": [
{
"decision_id": "dec_4d5e6f708192a3b4c5d6e7f8091a2b3c",
"task": "selector_survival",
"decision": "breaks",
"value": "breaks",
"p": 0.78,
"probabilities": {
"survives": 0.22,
"breaks": 0.78
},
"threshold": 0.6,
"defer_reason": null,
"decided_by": "model",
"rule": null,
"model": {
"release": "v.beta.5",
"version": "1.2.0",
"content_hash": "sha256:5d21f0e9c4a7b3e8",
"gate_passed": true
},
"locator_id": "checkout.apply-coupon"
},
{
"decision_id": "dec_5e6f708192a3b4c5d6e7f8091a2b3c4d",
"task": "selector_survival",
"decision": "survives",
"value": "survives",
"p": 0.96,
"probabilities": {
"survives": 0.96,
"breaks": 0.04
},
"threshold": 0.6,
"defer_reason": null,
"decided_by": "model",
"rule": null,
"model": {
"release": "v.beta.5",
"version": "1.2.0",
"content_hash": "sha256:5d21f0e9c4a7b3e8",
"gate_passed": true
},
"locator_id": "nav.account-menu"
}
]
}
}
]
}{
"error": {
"type": "invalid_request",
"message": "At most 100 items per batch.",
"param": "items",
"request_id": "req_01JDXK8B9C0D1E2F3G4H5J6K7L"
}
}Request body
modelstringRequiredAlways
ostra-lite.Valueostra-liteitemsarray of objectsRequiredThe tasks to run. Each item counts as one request against your rate limit.
1–100 itemsShow 3 child fieldsHide child fields
custom_idstringYour id for the item, echoed in its result. Longer values are cut to 128 characters.
0–128 charstaskstringRequiredWhich task to run.
One oftriagetest_impactselector_survivalinputobjectRequiredThe task’s input, as for
/predict.
Response
idstringRequest id.
modelstringThe model and release that answered.
billedobjectWhat this request cost. Cached answers cost 0.
Show 3 child fieldsHide child fields
unitsintegerBillable units: 1 per failure (triage), 1 per request (test impact), 1 per locator (selector survival). 0 for a cached answer.
costNanointegerCost in nano-dollars (1 USD = 1,000,000,000).
costUsdstringCost in USD as an exact decimal string, e.g.
"0.0000005".
resultsarray of objectsOne result per item, in input order.
Show 6 child fieldsHide child fields
custom_idstringYour
custom_id, when you sent one.okbooleantruewhen the item answered.taskstringThe item’s task.
cachedbooleanWhen
ok: the answer came from cache.outputobjectWhen
ok: the task’s answer, as for/predict.errorobjectWhen not
ok:{ "type", "message" }.Show 2 child fieldsHide child fields
typestringError type, e.g.
invalid_requestorupstream_error.messagestringWhat went wrong.
Response headers
x-request-idstringId of this request (
req_+ 26 characters). Quote it to support.ostra-ratelimit-requests-limitintegerYour workspace’s requests-per-minute limit.
ostra-ratelimit-requests-remainingintegerRequests left in the current minute.
ostra-ratelimit-requests-resetintegerSeconds until the current minute ends and the count resets.
ostra-balance-remaining-usdstringWorkspace credit balance after this request, in USD. Approximate under concurrent requests.
Errors
| Status | Type | When |
|---|---|---|
| 400 | invalid_request | items is missing, empty, or longer than 100. Per-item problems come back inside results instead. |
| 413 | payload_too_large | The body is larger than 2 MB. |
| 401 | authentication_error | The API key is missing, malformed, unknown, revoked or expired. |
| 403 | permission_error | The caller’s IP isn’t in the key’s allowlist, or a read-only key called a route that needs full access. |
| 402 | insufficient_balance | Your credit balance doesn’t cover the request. Nothing is charged. |
| 402 | spend_limit_reached | The workspace’s monthly spend limit (scope: "org") or this key’s monthly spend cap (scope: "key") is reached. |
| 429 | rate_limit_exceeded | The workspace’s requests-per-minute limit is reached. Wait Retry-After seconds. |
| 503 | service_unavailable | Too many requests are updating the workspace balance at once. Nothing was charged; retry after Retry-After (1 s). |
Every error has the same envelope and a request_id. See Errors for messages and retry advice.