Manejo de errores
La API usa códigos de estado HTTP estándar. Un código 2xx indica éxito; 4xx, un problema con la petición; 5xx, un error del servidor.
Códigos de estado
| Código HTTP | Campo code | Significado |
|---|---|---|
| 200 OK | SUCCESS / UPDATED / DELETED | Petición exitosa. |
| 201 Created | CREATED | Recurso creado correctamente. |
| 400 Bad Request | BAD_REQUEST / VALIDATION_ERROR | Petición mal formada (BAD_REQUEST) o datos que no pasan la validación (VALIDATION_ERROR). |
| 401 Unauthorized | UNAUTHORIZED | Falta el token, o el token es inválido, fue revocado o expiró. |
| 403 Forbidden | FORBIDDEN | El plan no incluye acceso a la API, la suscripción venció, o al token le falta un scope requerido. |
| 404 Not Found | NOT_FOUND | El recurso solicitado no existe. |
| 409 Conflict | CONFLICT | La petición entra en conflicto con el estado actual del recurso. |
| 422 Unprocessable Entity | UNPROCESSABLE_ENTITY | La petición está bien formada pero no se puede procesar. |
| 429 Too Many Requests | RATE_LIMITED | Se superó el límite de frecuencia. |
| 500 Internal Server Error | INTERNAL_ERROR | Error interno del servidor. |
| 503 Service Unavailable | SERVICE_UNAVAILABLE | El servicio no está disponible temporalmente. |
Formato de los errores
Las respuestas de error son un objeto JSON con success en false, un mensaje descriptivo en error y un identificador legible en code.
{
"success": false,
"error": "Token missing required scopes: products:write",
"code": "FORBIDDEN"
}Errores de validación
Cuando un POST o PUT falla por validación, la API responde 400 con code VALIDATION_ERROR e incluye además un array errors con el detalle por campo.
{
"success": false,
"error": "Validation failed",
"code": "VALIDATION_ERROR",
"errors": [
{
"field": "name",
"message": "This field is required",
"code": "required",
"value": null
}
]
}Cómo manejarlos
- 400: revisá el cuerpo de la petición y los mensajes de validación que devuelve la API.
- 401: verificá que estás enviando el token y que sigue activo; si fue revocado o expiró, generá uno nuevo.
- 403: confirmá que la cuenta tiene plan Premium y que el token incluye el scope necesario para ese endpoint.
- 404: revisá la URL y el ID del recurso.
- 429: esperá y reintentá con backoff exponencial (ver la sección Límites de uso).
- 5xx: reintentá más tarde; si persiste, consultá el estado del servicio en status.yo-facturo.com.