Skip to content

Every error has the same shape:

{ "error": { "code": "dte_invalido", "message": "…", "details": {} } }

Always branch on code, never on the text of message (which is in Spanish). Codes are a public contract and are never renamed.

HTTP code What happened What to do
400 datos_invalidos Invalid body or parameters; details = [{ ruta, mensaje }] Fix each path and retry.
400 dte_invalido The DTE doesn’t match the MH schema; details.problemas = [{ ruta, mensaje, regla }]. Nothing was issued Fix and validate again.
401 no_autenticado No session, or the key is invalid, revoked, or expired Check the key or create another.
402 plan_requerido The account’s plan doesn’t include the operation (cloud only) Upgrade your plan; no control number was consumed.
403 sin_permiso The details.permiso permission is missing Use a key with that permission.
403 origen_no_permitido Cookie-authenticated request from another origin Use the dashboard or an API key.
404 no_encontrado The resource doesn’t exist in your organization Check the id or the code.
409 sin_organizacion, sin_organizacion_activa The session has no active organization Create or activate an organization.
409 emisor_no_configurado, credenciales_incompletas, sin_punto_venta Configuration is missing Complete it in the dashboard (Issuer).
409 nit_bloqueado The issuer’s NIT can’t be changed after documents have been issued Create another organization for another NIT.
409 estado_invalido The document isn’t in a status that allows the operation Fetch the document.
409 ambiente_distinto The document or event belongs to another environment Use the key for the right environment.
409 retorno_excedido The return exceeds what is left of the document details.disponible says how much is left.
409 retorno_vigente The document has an active return Invalidate the return first (details.codigoGeneracion).
409 idempotencia_distinta That Idempotency-Key was already used with a different body A different key for a different document; the same body for the same one.
409 idempotencia_en_curso The first attempt is still in progress or its result couldn’t be confirmed Wait and retry with the same key. If it persists (the reservation lasts until the key expires, 24 h), check your documents before using another key.
409 cliente_repetido, producto_repetido, codigo_repetido A record with that document or code already exists Update the existing one.
409 clientes_solo_produccion Saved clients only exist in production (test key or test environment) In test, send the recipient in datos.receptor.
409 limite_webhooks The organization already has 10 webhooks Delete one you don’t use.
409 sin_archivo The document is still pending and has no file yet Check again in a few minutes.
409 simulador_inactivo Test credentials requested from a server without the simulator Upload real MH credentials.
422 dte_rechazado The MH rejected the document; the control number is left as rejected Show details.mh.observaciones, fix, and issue a new one with another Idempotency-Key.
422 invalidacion_rechazada The MH rejected the invalidation (often, past the deadline) Check details.mh and the deadlines.
422 contingencia_rechazada The MH rejected the contingency event Check details.mh.
422 evento_rechazado The MH rejected a return or special operations event Fix and resend with another Idempotency-Key.
429 limite_excedido Too many requests Wait Retry-After seconds.
429 limite_plan The plan limit was reached, e.g. DTEs per month (cloud only) Upgrade your plan or wait for the next period; no control number was consumed.
500 error_interno Unexpected server error Retry; if it persists, report it.
502 mh_credenciales_rechazadas The MH didn’t accept the API password or the certificate Check Company & Tax Authority → MH credentials.
502 mh_no_disponible Couldn’t reach the MH; no control number was consumed Retry with the same Idempotency-Key.
502 emision_fallida Signing failed; the document was left rechazado without being transmitted Check the certificate and issue again.
502 emision_incierta The outcome couldn’t be confirmed; the document stays pendiente Don’t issue another one. Check details.codigoGeneracion; it reconciles with the MH on its own.
502 evento_incierto Couldn’t confirm whether the MH received the return or special operations event Don’t send it again. Check details.codigoGeneracion with the MH; resend with another Idempotency-Key only if it didn’t arrive.

In details.mh the MH reports { codigo, mensaje, observaciones[] }.

The /api/auth/* routes (Better Auth) answer { "code": "…", "message": "…" }, without the error object. Besides Better Auth’s own codes:

HTTP code What happened What to do
400 datos_invalidos A name, slug, logo, image or metadata exceeds its limit Shorten it; image and logo must be an https:// URL.
403 turnstile_invalido The Turnstile token is missing, invalid, or from another screen Solve the widget again and retry.
429 demasiados_reenvios Several confirmation links were already sent to that email this hour Use the latest link or «Olvidé mi contraseña».
429 demasiados_intentos Too many password attempts while confirming the email Set a new password from the same link.

For AI assistants: llms.txt ·llms-full.txt ·every page as Markdown by adding .md to its path.