Errors

The DecimalAI API uses standard HTTP status codes and returns structured JSON error bodies.

Error response shape

{
  "detail": "Skill 'search-flights' not found"
}

For validation errors raised by Pydantic, detail stays a string and the per-field errors are attached under details.errors:

{
  "detail": "Request validation failed",
  "code": "validation_error",
  "request_id": "2a47c3a3-724",
  "details": {
    "errors": [
      {
        "field": "body.agent_name",
        "message": "Field required"
      }
    ]
  }
}

Status codes

Code	Meaning	Common causes	What to do
200	OK	Request succeeded.	Use the response body.
201	Created	Resource created (skill, dataset, API key).	Persist the returned ID.
400	Bad Request	Missing field, malformed JSON, invalid enum value, or webhook signature mismatch.	Check the `detail` for the failing field; fix the request body and retry.
401	Unauthorized	Missing or invalid API key, expired Clerk session, or webhook signature header missing.	Re-issue the API key from Settings → API Keys. Confirm the header is `Authorization: Bearer dai_sk_...`.
402	Payment Required	Plan quota exhausted (traces ingested, SFT rows, or other metered resource).	Upgrade the plan in Settings → Billing, or wait for the next billing period. The `detail` names the exhausted metric.
403	Forbidden	Your role lacks permission for this action, or you’re attempting to access a workspace you don’t belong to.	Ask a workspace admin to grant the required role, or scope the action to a workspace you have access to.
404	Not Found	The named resource (trace ID, skill name, manifest ID, dataset version) doesn’t exist or has been deleted.	Check the resource ID; verify it exists with a `list` call.
409	Conflict	Idempotency conflict — e.g., installing a registry skill that’s already installed, or syncing a skill whose body hash matches an existing version.	This is usually safe to ignore. The conflicting resource is returned in `detail`.
422	Unprocessable Entity	Request validation failed (Pydantic).	The `details.errors` array lists each invalid field.
429	Too Many Requests	Rate limit exceeded for your plan tier.	Honor the `Retry-After` response header and back off. See the Tracing guide for batch ingest patterns that reduce request count.
500	Internal Server Error	Unhandled exception on the backend.	Retry with backoff; if persistent, file a support request with the response `X-Request-ID` header.
501	Not Implemented	Feature is gated, deprecated, or not enabled on your plan.	Check the Pricing page for plan availability.
503	Service Unavailable	Backend overloaded or in maintenance.	Retry with backoff; if persistent, email hello@decimal.ai with your `X-Request-ID`.

Idempotency

Several endpoints are idempotent by design:

POST /api/v1/manifests — same manifest_hash returns the existing manifest_id with "is_new": false and "action": "deduped".
POST /api/v1/skills/sync — returns per-batch counts, {"status": "ok", "created": 2, "updated": 1, "unchanged": 5}; unchanged skills fall into unchanged, changes auto-create a new version.
POST /api/v1/traces — duplicate trace_id returns the existing trace.

Re-running these is safe and will not double-count toward your quota.

Rate limits

Rate limits are applied per API key, using one token bucket that covers the whole API surface — there is no separate ingest budget. The bucket is sized from the key’s organization plan:

Plan	RPM	Burst
Free	60	10
Core	120	20
Pro	300	50
Enterprise	1,000+	200+

When you hit a limit, responses include:

HTTP/1.1 429 Too Many Requests
Retry-After: 12

The SDK respects Retry-After automatically. If you’re calling the API directly, sleep for the indicated number of seconds before retrying.

Reporting an issue

For 5xx errors or unexpected behavior, include the X-Request-ID response header when filing a support ticket — it lets us look up the failing request in logs.

Overview

Traces

Evaluations

Replay

Skills

Manifests

Datasets

Registry

Error response shape

Status codes

Idempotency

Rate limits

Reporting an issue

​Error response shape

​Status codes

​Idempotency

​Rate limits

​Reporting an issue

Error response shape

Status codes

Idempotency

Rate limits

Reporting an issue