Skip to main content
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 is a list of structured field errors: 
{
  "detail": [
    {
      "loc": ["body", "agent_name"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

​
Status codes

CodeMeaningCommon causesWhat to do
200OKRequest succeeded.Use the response body.
201CreatedResource created (skill, dataset, API key).Persist the returned ID.
400Bad RequestMissing field, malformed JSON, invalid enum value, or webhook signature mismatch.Check the detail for the failing field; fix the request body and retry.
401UnauthorizedMissing 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_....
402Payment RequiredPlan 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.
403ForbiddenYour 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.
404Not FoundThe 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.
409ConflictIdempotency 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.
422Unprocessable EntityRequest validation failed (Pydantic).The detail array lists each invalid field.
429Too Many RequestsRate 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.
500Internal Server ErrorUnhandled exception on the backend.Retry with backoff; if persistent, file a support request with the response X-Request-ID header.
501Not ImplementedFeature is gated, deprecated, or not enabled on your plan.Check the Pricing page for plan availability.
503Service UnavailableBackend overloaded or in maintenance.Retry with backoff; if persistent, email support@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 status: "existing".
  • POST /api/v1/skills/sync — unchanged skills return {"status": "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

Indicative rate limits per plan tier (the per-minute numbers are illustrative targets, not a hard contract — limiting is currently global rather than per-plan-enforced):
PlanTrace ingest (per min)Read endpoints (per min)
Free60120
Core6001,200
Pro1,8003,600
EnterpriseCustomCustom
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.