RFC 9457 · Stable codes · Resolution hints

ecentic API errors.

Every failure on the ecentic API is a typed problem document, not an HTML page. The code is the contract: it is stable, machine-readable, and safe to branch on.

Back to the docs

The shape of a problem

One media type, one schema, on every 4xx and 5xx the API returns.

Responses carry Content-Type: application/problem+json — deliberately not application/json, because the media type is how a generic client knows the body describes a failure rather than the resource it asked for.

type — URI naming the error, anchored in this page
code — the stable machine-readable identifier to branch on
title — short human summary
status — the HTTP status, repeated in the body
detail — what went wrong on this specific request
resolution — what to do about it
instance — the path that produced it, when known

HTTP/1.1 404 Not Found
Content-Type: application/problem+json; charset=utf-8

{
  "type": "https://ecentic.ai/docs/errors#not-found",
  "title": "Resource not found",
  "status": 404,
  "code": "not-found",
  "detail": "No ecentic API endpoint at GET /api/v1/widgets.",
  "resolution": "Check the path against the OpenAPI document at /openapi.json or the API catalog at /.well-known/api-catalog.",
  "documentation": "https://ecentic.ai/docs/errors",
  "instance": "/api/v1/widgets"
}

Error catalogue

Codes are frozen once published. Titles and hints may be reworded; codes may not.

Code	Status	Meaning	How to resolve
not-found	404	Resource not found	Check the path against the OpenAPI document at /openapi.json or the API catalog at /.well-known/api-catalog.
method-not-allowed	405	Method not allowed	Re-read the operation in /openapi.json; the `Allow` header lists the methods this path accepts.
unauthenticated	401	Authentication required	Send `Authorization: Bearer ecentic_sk_…`. Registration and key minting are documented at /auth.md.
unauthorized	403	Not permitted	The credential is valid but lacks the scope for this operation. Scopes are listed at /.well-known/oauth-protected-resource.
payment-required	402	Payment required	Settle the x402 challenge in the `PAYMENT-REQUIRED` header, or use the free discovery surfaces under /.well-known and /api/v1.
subscription-required	402	Subscription required	This operation needs an active ecentic plan. Plans are listed at /api/v1/plans and purchasable at /pricing.
invalid-request	400	Invalid request	Compare the request body against the operation's request schema in /openapi.json.
validation-failed	422	Request failed validation	Fix the fields named in `errors` and retry. Field schemas live in /openapi.json.
conflict	409	Conflicting state	The resource already exists or has changed. Re-read it and retry with the current state.
rate-limited	429	Rate limit exceeded	Wait for the number of seconds in `Retry-After`, then retry. The active policy is in the `RateLimit-Policy` header and documented at /docs/rate-limits.
upstream-timeout	504	Upstream timed out	Retry with exponential backoff; the failure is transient.
internal-error	500	Internal error	Retry with exponential backoff. If it persists, report it at /support with the `instance` value from this response.

Docs Rate limits