QAPI está en beta — la API puede cambiar sin previo aviso. Usá sandbox para pruebas.
QAPIQAPIDocs · by DTEVIA
Guías

Manejo de Errores

Catálogo completo de errores (RFC 9457 Problem Details) de QAPI y cómo manejarlos en tu integración.

QAPI usa Problem Details for HTTP APIs (RFC 9457) para todos los errores. Cada respuesta de error tiene una URL type que apunta a la documentación específica del error, y se sirve con Content-Type: application/problem+json.

Formato de error

Ejemplo de respuesta

{
  "type": "https://docs.dtevia.com.gt/errors/validation-error",
  "title": "VALIDATION_ERROR",
  "status": 422,
  "detail": "Error de validación",
  "instance": "/v1/invoices",
  "invalid_params": [
    {
      "field": "items.0.impuestos.0.monto_impuesto",
      "message": "MontoImpuesto IVA inválido. Esperado ~12.00, recibido 10.00"
    }
  ]
}

Campos del objeto

CampoDescripción
typeURL de documentación del error. Siempre resuelve a una página en esta documentación.
titleCódigo del error en MAYÚSCULAS (constante, seguro para comparar en código)
statusCódigo HTTP
detailDescripción legible en español
instanceEndpoint que generó el error
invalid_paramsSolo en errores de validación. Lista de {field, message} con los campos que fallaron. message siempre es texto legible.
contextSolo en errores operativos (cuotas, límites, habilitación). Objeto con los datos de ese error; su forma depende del title — cada página del catálogo documenta la suya.

No confundas invalid_params con context

Son dos extensiones distintas y no intercambiables. invalid_params responde "qué campo de tu request está mal"; context responde "con qué números te topaste" (cuánto llevás usado, cuál es el tope, qué proyecto). Un error nunca trae los datos operativos dentro de invalid_params: si iterás esa lista buscando message en un 429 de cuota, no vas a encontrar nada — lo que buscás está en context.


Catálogo de errores

error_code de factura ≠ errores HTTP

Una factura FAILED trae error_code: "SIGN_FAILED" o "CERT_FAILED" (también en el webhook invoice.failed). Son códigos del pipeline de certificación, un namespace distinto a los errores HTTP de este catálogo. Cuando el rechazo viene del certificador, error_message arranca con Regla SAT <código>: qué significa cada uno y cómo corregirlo está en Reglas SAT.


Manejo de errores en código

Por tipo de error

interface QapiError {
  type: string;
  title: string;
  status: number;
  detail: string;
  instance?: string;
  /** Campos que fallaron. Solo en errores de validación. */
  invalid_params?: { field: string; message: string }[];
  /** Datos del error operativo. Su forma depende del `title`. */
  context?: Record<string, unknown>;
}

async function emitirFactura(payload: InvoicePayload): Promise<Invoice> {
  const res = await fetch('https://api.dtevia.com.gt/v1/invoices', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.QAPI_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(payload),
  });

  if (!res.ok) {
    const error: QapiError = await res.json();

    switch (error.status) {
      case 422:
        // Error de validación — mostrale al usuario los campos inválidos
        const fields = error.invalid_params?.map(p => `${p.field}: ${p.message}`).join('\n');
        throw new ValidationError(`Factura inválida:\n${fields}`);

      case 429:
        // Solo RATE_LIMITED se resuelve esperando: trae Retry-After. Los 429 de cuota
        // (SANDBOX_LIMIT_REACHED, MONTHLY_QUOTA_EXCEEDED, OVERAGE_CAP_REACHED) no.
        if (error.title === 'RATE_LIMITED') {
          throw new RateLimitError(`Reintenta en ${res.headers.get('retry-after')}s`);
        }
        throw new QuotaError(error.detail);

      case 401:
      case 403:
        throw new AuthError(error.detail);

      default:
        // Error del servidor — loggea el X-Request-ID para soporte
        const requestId = res.headers.get('x-request-id');
        throw new Error(`Error QAPI [${requestId}]: ${error.detail}`);
    }
  }

  return res.json();
}
import axios, { AxiosError } from 'axios';

async function emitirFactura(payload: InvoicePayload): Promise<Invoice> {
  try {
    const { data } = await axios.post(
      'https://api.dtevia.com.gt/v1/invoices',
      payload,
      { headers: { Authorization: `Bearer ${process.env.QAPI_API_KEY}` } }
    );
    return data;
  } catch (err) {
    if (!axios.isAxiosError(err) || !err.response) throw err;

    const error = err.response.data;

    if (error.status === 422 && error.invalid_params) {
      const fields = error.invalid_params.map((p: any) => `${p.field}: ${p.message}`);
      throw new Error(`Validación fallida: ${fields.join('; ')}`);
    }

    throw new Error(`QAPI Error ${error.status}: ${error.detail}`);
  }
}
class QapiValidationError(Exception):
    def __init__(self, invalid_params: list):
        self.invalid_params = invalid_params
        fields = ", ".join(f"{p['field']}: {p['message']}" for p in invalid_params)
        super().__init__(f"Validación fallida: {fields}")

def emitir_factura(payload: dict) -> dict:
    res = httpx.post(
        "https://api.dtevia.com.gt/v1/invoices",
        json=payload,
        headers={"Authorization": f"Bearer {QAPI_API_KEY}"},
    )

    if res.status_code != 202:
        error = res.json()

        if error["status"] == 422:
            raise QapiValidationError(error.get("invalid_params", []))

        raise Exception(f"QAPI Error {error['status']}: {error['detail']}")

    return res.json()

URLs de documentación de errores

Cómo funcionan los enlaces type

El campo type de cada error apunta a https://docs.dtevia.com.gt/errors/{slug}. Es un atajo: redirige (308) a la página de esta documentación que explica la causa y la solución de ese error, en /docs/errores/{slug}. Podés usar cualquiera de las dos formas — la corta es la que viaja en las respuestas de la API.

Si tu backend genera un error con type: "https://docs.dtevia.com.gt/errors/validation-error", un desarrollador que haga click en esa URL llega directamente a la explicación de las 21 validaciones. No necesitás documentar los errores vos mismo.

En esta página