Catalogo de errores

1001 HTTP 401 API key invalida auth

Que significa: La API key no fue proporcionada, esta mal formada o no existe.

Como resolverlo: Verifica que el header Authorization diga Bearer sat_xxx (no Basic, no solo la key).

Ejemplo de respuesta:

{
  "cfdi_codigo": 1001,
  "cfdi_texto": "API key invalida",
  "cfdi_descripcion": "La API key no fue proporcionada, esta mal formada o no existe.",
  "saldo": 42
}

1002 HTTP 401 API key revocada o expirada auth

Que significa: La API key fue revocada o ya no esta activa.

Como resolverlo: Genera una nueva API key en el Panel (RFCs > API keys) y actualiza tu aplicacion.

Ejemplo de respuesta:

{
  "cfdi_codigo": 1002,
  "cfdi_texto": "API key revocada o expirada",
  "cfdi_descripcion": "La API key fue revocada o ya no esta activa.",
  "saldo": 42
}

1003 HTTP 403 Operacion no habilitada auth

Que significa: El RFC no tiene habilitada esta operacion.

Como resolverlo: Habilita la operacion en Panel > Operaciones (algunas requieren plan premium).

Ejemplo de respuesta:

{
  "cfdi_codigo": 1003,
  "cfdi_texto": "Operacion no habilitada",
  "cfdi_descripcion": "El RFC no tiene habilitada esta operacion.",
  "saldo": 42
}

1004 HTTP 402 Saldo insuficiente saldo

Que significa: Tu cuenta no tiene creditos suficientes para esta operacion.

Como resolverlo: Recarga creditos en Panel > Saldos > Recargar. 1 credito = 1 consulta normal.

Ejemplo de respuesta:

{
  "cfdi_codigo": 1004,
  "cfdi_texto": "Saldo insuficiente",
  "cfdi_descripcion": "Tu cuenta no tiene creditos suficientes para esta operacion.",
  "saldo": 42
}

2001 HTTP 400 Parametros invalidos validacion

Que significa: Faltan parametros requeridos o tienen formato incorrecto.

Como resolverlo: Revisa el nombre y tipo de cada parametro en la seccion Parametros del endpoint.

Ejemplo de respuesta:

{
  "cfdi_codigo": 2001,
  "cfdi_texto": "Parametros invalidos",
  "cfdi_descripcion": "Faltan parametros requeridos o tienen formato incorrecto.",
  "saldo": 42
}

2002 HTTP 400 RFC invalido validacion

Que significa: El RFC no tiene formato valido (debe ser 12 o 13 caracteres alfanumericos).

Como resolverlo: Verifica que el RFC este bien escrito. Ejemplos validos: XAXX010101000, ABC010101AAA.

Ejemplo de respuesta:

{
  "cfdi_codigo": 2002,
  "cfdi_texto": "RFC invalido",
  "cfdi_descripcion": "El RFC no tiene formato valido (debe ser 12 o 13 caracteres alfanumericos).",
  "saldo": 42
}

2003 HTTP 400 e.firma invalida validacion

Que significa: Los archivos .cer o .cer.key no son validos, estan vencidos o no corresponden al RFC.

Como resolverlo: Sube archivos vigentes desde el portal del SAT y verifica que coincidan con el RFC.

Ejemplo de respuesta:

{
  "cfdi_codigo": 2003,
  "cfdi_texto": "e.firma invalida",
  "cfdi_descripcion": "Los archivos .cer o .cer.key no son validos, estan vencidos o no corresponden al RFC.",
  "saldo": 42
}

2004 HTTP 400 Password del e.firma incorrecta validacion

Que significa: La contrasena del archivo .cer.key es incorrecta.

Como resolverlo: Intenta con la contrasena que usaste al exportar el e.firma del portal del SAT.

Ejemplo de respuesta:

{
  "cfdi_codigo": 2004,
  "cfdi_texto": "Password del e.firma incorrecta",
  "cfdi_descripcion": "La contrasena del archivo .cer.key es incorrecta.",
  "saldo": 42
}

3001 HTTP 502 SAT no disponible sistema

Que significa: El portal del SAT no responde o esta en mantenimiento.

Como resolverlo: Espera unos minutos y reintenta. Si persiste, consulta el status del SAT.

Ejemplo de respuesta:

{
  "cfdi_codigo": 3001,
  "cfdi_texto": "SAT no disponible",
  "cfdi_descripcion": "El portal del SAT no responde o esta en mantenimiento.",
  "saldo": 42
}

3002 HTTP 504 Timeout del SAT sistema

Que significa: El SAT no respondio en 30 segundos.

Como resolverlo: Reintenta la operacion. Si falla varias veces, contacta soporte.

Ejemplo de respuesta:

{
  "cfdi_codigo": 3002,
  "cfdi_texto": "Timeout del SAT",
  "cfdi_descripcion": "El SAT no respondio en 30 segundos.",
  "saldo": 42
}

3003 HTTP 502 SAT rechazo la consulta sistema

Que significa: El SAT devolvio un error no esperado.

Como resolverlo: Revisa los parametros de entrada. Si todo esta bien, contacta soporte con el UUID.

Ejemplo de respuesta:

{
  "cfdi_codigo": 3003,
  "cfdi_texto": "SAT rechazo la consulta",
  "cfdi_descripcion": "El SAT devolvio un error no esperado.",
  "saldo": 42
}

4001 HTTP 429 Demasiadas peticiones rate

Que significa: Superaste el limite de peticiones por minuto (60 req/min).

Como resolverlo: Espera 60 segundos. Para limites mayores, contactanos para whitelisting.

Ejemplo de respuesta:

{
  "cfdi_codigo": 4001,
  "cfdi_texto": "Demasiadas peticiones",
  "cfdi_descripcion": "Superaste el limite de peticiones por minuto (60 req/min).",
  "saldo": 42
}

4002 HTTP 429 Limite diario alcanzado rate

Que significa: Superaste el limite diario de tu plan.

Como resolverlo: Espera al siguiente dia o upgrade tu plan.

Ejemplo de respuesta:

{
  "cfdi_codigo": 4002,
  "cfdi_texto": "Limite diario alcanzado",
  "cfdi_descripcion": "Superaste el limite diario de tu plan.",
  "saldo": 42
}

5001 HTTP 500 Error interno interno

Que significa: Error inesperado del servidor. La operacion NO se desconto.

Como resolverlo: Reintenta. Si persiste, contacta soporte con el UUID.

Ejemplo de respuesta:

{
  "cfdi_codigo": 5001,
  "cfdi_texto": "Error interno",
  "cfdi_descripcion": "Error inesperado del servidor. La operacion NO se desconto.",
  "saldo": 42
}

5002 HTTP 503 Servicio en mantenimiento interno

Que significa: El sistema esta en mantenimiento programado.

Como resolverlo: Revisa https://panel.cfdi4.com para avisos de mantenimiento.

Ejemplo de respuesta:

{
  "cfdi_codigo": 5002,
  "cfdi_texto": "Servicio en mantenimiento",
  "cfdi_descripcion": "El sistema esta en mantenimiento programado.",
  "saldo": 42
}

6001 HTTP 400 User-Agent no permitido cliente

Que significa: No enviaste header User-Agent o es muy generico.

Como resolverlo: Anade -H "User-Agent: MiApp/1.0" a tu peticion. Evita "curl/7.x" o vacio.

Ejemplo de respuesta:

{
  "cfdi_codigo": 6001,
  "cfdi_texto": "User-Agent no permitido",
  "cfdi_descripcion": "No enviaste header User-Agent o es muy generico.",
  "saldo": 42
}

6002 HTTP 400 Content-Type incorrecto cliente

Que significa: No enviaste Content-Type: application/json.

Como resolverlo: Anade -H "Content-Type: application/json" en POST.

Ejemplo de respuesta:

{
  "cfdi_codigo": 6002,
  "cfdi_texto": "Content-Type incorrecto",
  "cfdi_descripcion": "No enviaste Content-Type: application/json.",
  "saldo": 42
}

6003 HTTP 400 Body JSON invalido cliente

Que significa: El body no es JSON valido.

Como resolverlo: Valida tu JSON antes de enviar. Usa json_encode() en tu lenguaje.

Ejemplo de respuesta:

{
  "cfdi_codigo": 6003,
  "cfdi_texto": "Body JSON invalido",
  "cfdi_descripcion": "El body no es JSON valido.",
  "saldo": 42
}

7001 HTTP 400 Vault no encontrado vault

Que significa: No se encontro el vault para el RFC solicitado.

Como resolverlo: Registra primero el vault con vault/rfc/registrar.

Ejemplo de respuesta:

{
  "cfdi_codigo": 7001,
  "cfdi_texto": "Vault no encontrado",
  "cfdi_descripcion": "No se encontro el vault para el RFC solicitado.",
  "saldo": 42
}

7002 HTTP 400 Vault ya existe vault

Que significa: Ya tienes un vault para este RFC.

Como resolverlo: Usa el endpoint de actualizar o elimina primero.

Ejemplo de respuesta:

{
  "cfdi_codigo": 7002,
  "cfdi_texto": "Vault ya existe",
  "cfdi_descripcion": "Ya tienes un vault para este RFC.",
  "saldo": 42
}