Conceptos
Errores
Todos los errores siguen el mismo shape JSON. Sigue las reglas de retry para 429 y 5xx. Cita el request_id si abres ticket.
Formato estándar
{
"error": {
"code": "plan_does_not_include_api",
"message": "El plan actual de tu organización no incluye acceso a la API.",
"request_id": "req_01h..."
}
}Códigos por status
| HTTP | code | Significado | Reintentar |
|---|---|---|---|
| 400 | invalid_request | Parámetros mal formados, fuera de rango. | No (corrige el request) |
| 401 | missing_api_key · invalid_api_key | Header ausente o clave inválida / revocada. | No (corrige la clave) |
| 403 | plan_does_not_include_api · scope_required | Plan insuficiente o scope insuficiente para el endpoint. | No (sube de plan) |
| 404 | not_found | Recurso no existe en tu organización. | No |
| 429 | rate_limited | Excediste la cuota. | Sí, espera Retry-After segundos |
| 500 | internal_error | Bug nuestro. Tenemos alerta automática. | Sí, backoff exponencial |
| 502 | upstream_error | El marketplace upstream falló (ML, Amazon, etc.). | Sí, backoff exponencial |
| 503 | service_unavailable | Mantenimiento programado o degradación. | Sí, espera 30s |
Política de reintentos recomendada
- 429 Rate limited: respeta el header
Retry-Afteral pie de la letra. No reintentes antes — solo te quemas más cuota. - 500 / 502 / 503: backoff exponencial con jitter. Empieza en 500ms, duplica hasta máximo 30s. Máximo 5 reintentos.
- Otros 4xx: no reintentes; el request está malformado.
Soporte
Si recibes un 500 persistente o un comportamiento inesperado, escríbenos a soporte@sellerp.com citando:
- El
X-Request-Idque devolvimos. - Tu organization_id (lo ves con
GET /v1/me). - El status code y el body de error que recibiste.
SLA de respuesta para incidentes técnicos: 1 día hábil.