RFC 9457 · Códigos estables · Pistas de resolución
Errores de la API de ecentic.
Cada fallo de la API de ecentic es un documento de problema tipado, no una página HTML. El código es el contrato: es estable, legible por máquinas y seguro para tomar decisiones.
La forma de un problema
Un solo tipo de medio y un solo esquema, en cada 4xx y 5xx que devuelve la API.
Las respuestas llevan `Content-Type: application/problem+json` — deliberadamente no `application/json`, porque el tipo de medio es la señal que permite a un cliente genérico saber que el cuerpo describe un fallo y no el recurso solicitado.
- `type` — URI que nombra el error, anclado en esta página
- `code` — identificador estable legible por máquinas sobre el que ramificar
- `title` — resumen breve para personas
- `status` — el estado HTTP, repetido en el cuerpo
- `detail` — qué falló en esta petición concreta
- `resolution` — qué hacer al respecto
- `instance` — la ruta que lo produjo, cuando se conoce
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"
}Catálogo de errores
Los códigos quedan congelados una vez publicados. Los títulos y las pistas pueden reformularse; los códigos no.
| Código | Estado | Significado | Cómo resolverlo |
|---|---|---|---|
| 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. |
| 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. |
¿Listo para ser el producto que recomiendan los agentes?
Instálalo gratis en Shopify o WooCommerce y mira tu puntuación de IA en minutos.
Instalar en Shopify
Instalar en WooCommerce
© 2026 ecentic. Todos los derechos reservados.
Hecho para comercios que se niegan a ser invisibles para la IA.