Errors
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[] }.
Session route errors
Section titled “Session route errors”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.