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

Get picked by AI

Ready to be the product agents recommend?

Install free on Shopify or WooCommerce and see your AI score in minutes.

Install on Shopify

Install on WooCommerce

Win every AI shopping agent's cart.

Built for the agent economy

Made for merchants who refuse to be invisible to AI.

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" }

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.