La API de Camtom usa codigos HTTP estandar. Los errores devuelven un objeto JSON con el tipo de error, un mensaje descriptivo y el codigo de estado.
Todas las respuestas de error de la API siguen esta estructura:
{
"error": "InvalidRequest",
"message": "El campo 'product_description' es requerido.",
"status_code": 400
}
Nombre del tipo de error. Corresponde al nombre de la clase de excepcion interna (ej. InvalidRequest, InvalidEncoding, InternalServerError).
Descripcion legible del error. Util para debugging y logs.
Codigo de estado HTTP del error.
Referencia de codigos
Errores del cliente (4xx)
| HTTP | Tipo de error | Descripcion | Causa comun |
|---|
400 | InvalidEncoding | Codificacion de caracteres invalida | El request contiene caracteres con codificacion no valida |
400 | CamtomDocsResourceError | Error de archivo o recurso | Archivo corrupto, no legible o URL no accesible |
401 | Unauthorized | Autenticacion fallida | API key ausente, invalida, revocada o expirada |
402 | CamtomDocsCreditError | Creditos insuficientes | No hay creditos suficientes para procesar el documento |
403 | Forbidden | Acceso denegado | Suscripcion no valida, expirada, o pais no permitido en plan free |
404 | CamtomDocsNotFoundError | Recurso no encontrado | El documento o recurso solicitado no existe |
422 | CamtomDocsValidationError | Error de validacion | JSON Schema invalido, campos requeridos ausentes o formato incorrecto |
429 | CamtomDocsLimitError | Limite de cuota excedido | Se excedio el limite de uso o cuota de la suscripcion |
Errores del servidor (5xx)
| HTTP | Tipo de error | Descripcion | Que hacer |
|---|
500 | InternalServerError | Error interno del servidor | Reintentar con backoff exponencial. Si persiste, contactar soporte |
502 | CamtomDocsProcessingError | Error en procesamiento de IA | El modelo de IA no pudo procesar el documento. Reintentar o simplificar la peticion |
Errores de validacion (422) - Detalle
Los errores de validacion de CamtomDocs incluyen un campo errors adicional con detalles por campo:
{
"error": "CamtomDocsValidationError",
"errors": [
"El campo 'json_response' no puede estar vacio",
"El campo 'document_type' es requerido"
]
}
Manejo de errores
Patron recomendado
import requests
import time
def call_camtom_api(url, headers, data, files=None, params=None, max_retries=3):
for attempt in range(max_retries):
response = requests.post(url, headers=headers, data=data, files=files, params=params)
if response.status_code == 200:
return response.json()
error_body = response.json()
error_type = error_body.get("error", "Unknown")
message = error_body.get("message", "Error desconocido")
# Errores que no se resuelven reintentando
if response.status_code in (400, 401, 402, 403, 404, 422):
raise Exception(f"Error {response.status_code} ({error_type}): {message}")
# Limite de cuota: esperar antes de reintentar
if response.status_code == 429:
wait_time = 2 ** attempt
print(f"Limite excedido. Reintentando en {wait_time}s...")
time.sleep(wait_time)
continue
# Error del servidor: reintentar con backoff exponencial
if response.status_code >= 500:
wait_time = 2 ** attempt
print(f"Error del servidor ({error_type}). Reintentando en {wait_time}s...")
time.sleep(wait_time)
continue
raise Exception("Maximo de reintentos alcanzado")
# Ejemplo de uso con TariffPro Mini
result = call_camtom_api(
url="https://api.camtomx.com/api/v3/tariffpro/tariffpro-mini",
headers={"Authorization": "Bearer sk_tu_api_key"},
params={"country_code": "MEX", "model": "pro"},
data={"product_description": "Tornillo de acero inoxidable M8x40mm"}
)
Escenarios comunes y soluciones
API key invalida (401)
{
"error": "Unauthorized",
"message": "Invalid or expired token",
"status_code": 401
}
Authorization tenga el formato Bearer sk_... y que la key no haya sido revocada. Genera una nueva key desde app.camtomx.com si es necesario.
Suscripcion no valida (403)
{
"error": "Forbidden",
"message": "Organization subscription is not active or not pro/enterprise",
"status_code": 403
}
pro o enterprise activa. Las API keys requieren uno de estos planes.
Pais no permitido (403)
{
"error": "Forbidden",
"message": "Your current plan only allows access to WORLD classifications.",
"status_code": 403
}
free solo pueden usar country_code=WORLD. Actualiza a plan pro para acceder a clasificaciones por pais.
Creditos insuficientes (402)
{
"error": "CamtomDocsCreditError",
"message": "Insufficient credits",
"status_code": 402
}
Error de validacion (422)
{
"error": "CamtomDocsValidationError",
"errors": [
"json_response cannot be empty"
]
}
json_data contenga un JSON valido con document_type, document_description y un json_response no vacio que cumpla con JSON Schema Draft 7.
Error de procesamiento (502)
{
"error": "CamtomDocsProcessingError",
"message": "AI processing failed",
"status_code": 502
}
Error de codificacion (400)
{
"error": "InvalidEncoding",
"message": "Invalid character encoding in request",
"status_code": 400
}
Si recibes errores de forma consistente y no puedes resolverlos, contacta al equipo de soporte en app.camtomx.com con el tipo de error, el mensaje completo y un ejemplo del request que genera el error. 
