Codigos de error API Camtom | Referencia

Referencia de errores HTTP de la API Camtom: 400, 401, 402, 403, 422, 429, 500 y 502. Causas y soluciones con ejemplos de codigo.

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.

Formato de error

Todas las respuestas de error de la API siguen esta estructura:

{
  "error": "InvalidRequest",
  "message": "El campo 'product_description' es requerido.",
  "status_code": 400
}

error · string

Nombre del tipo de error. Corresponde al nombre de la clase de excepcion interna (ej. InvalidRequest, InvalidEncoding, InternalServerError).

message · string

Descripcion legible del error. Util para debugging y logs.

status_code · number

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

Python

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
}

Solucion: Verifica que el header 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
}

Solucion: Verifica que tu organizacion tenga una suscripcion 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
}

Solucion: Las organizaciones con plan 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
}

Solucion: Recarga creditos desde Settings > Billing en app.camtomx.com.

Error de validacion (422)

{
  "error": "CamtomDocsValidationError",
  "errors": [
    "json_response cannot be empty"
  ]
}

Solucion: Revisa que el campo 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
}

Solucion: Reintenta la peticion. Si el error persiste, verifica que el documento sea legible y que el schema no sea excesivamente complejo.

Error de codificacion (400)

{
  "error": "InvalidEncoding",
  "message": "Invalid character encoding in request",
  "status_code": 400
}

Solucion: Asegurate de que el request use codificacion UTF-8.

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.