Error codes
When a request to NOPAL's API fails, the response carries an HTTP code and a JSON body with the reason. This page explains each code, with the real messages the core returns and what to do.
Shape of the response
{ "detail": "Permiso insuficiente" }
detailis human-readable text. The interface shows it as is in a notice.- The server's messages are always in Spanish, whatever the interface language.
- Some errors add a sibling field without changing
detail:
| Extra field | Where | What for |
|---|---|---|
error_code | When registering a network printer | A stable code (see below) the guided wizard uses to word its message |
retry_after | 502 responses from NOPAL Intelligence | Seconds the AI provider asks you to wait before retrying. The interface shows the countdown |
- Validation errors generated by the framework itself (missing parameters or the wrong type) answer
422withdetailas a list of objects, not as text.
HTTP codes
| Code | Means | detail examples | What to do |
|---|---|---|---|
| 400 | The request is wrong: a value is not valid | "Ruta inválida" (invalid path), "Nombre de archivo inválido" (invalid file name), "IP inválida" (invalid IP), "Tipo no válido" (invalid type), "Formato no válido (xml o pdf)", "Todavía no hay un servidor de IA configurado" (no AI server configured yet) | Fix the value indicated. When registering a network printer, look at the error_code |
| 401 | There is no session or it is not valid | "No autenticado" (not authenticated), "Sesión inválida" (invalid session), "Usuario o contraseña incorrectos" (wrong username or password) | Sign in again |
| 403 | There is a session, but your role is not enough | "Permiso insuficiente" (insufficient permission), "Las acciones de la IA están desactivadas" (AI actions are off) | Ask an administrator. See Roles by action |
| 404 | What you ask for does not exist | "Archivo no encontrado" (file not found), "Carpeta no encontrada" (folder not found), "El plugin no está instalado" (the plugin is not installed), "Usuario no encontrado" (user not found), "Elemento no encontrado en la cola" (item not found in the queue) | Refresh the list: someone may have deleted or moved it |
| 409 | Conflict with the current state of the machine or the data | "No se pudo pausar / reanudar / cancelar la impresión" (could not pause / resume / cancel the print), "Ya hay un trabajo en curso en este láser" (a job is already running on this laser), "La placa no tiene una tarjeta SD lista" (the board has no SD card ready), "La carpeta ya existe" (the folder already exists), "Actualización bloqueada: hay trabajos activos…" (update blocked: there are active jobs) | Wait for the job to finish or change what clashes. To update NOPAL, stop the machines first |
| 413 | A file is too large | "La imagen pesa más de 15 MB" (the image weighs more than 15 MB) | Use a smaller file. It is the "Image to drawing" limit |
| 422 | The request is correct but cannot be processed | "Ese archivo no tiene ningún movimiento de corte, no hay nada que encuadrar" (that file has no cutting move, there is nothing to frame), or a list of validation errors | Check the file or the parameters |
| 429 | Too many attempts | "Demasiados intentos; vuelve a intentarlo en unos minutos" (too many attempts; try again in a few minutes) | It is the sign-in limit: 5 failures in 5 minutes. Wait. See Security |
| 500 | Unexpected server failure | "No se pudo guardar la configuración…" (could not save the configuration), "No se pudo leer el estado de git" (could not read the git state), "Este plugin no tiene un repositorio configurado" (this plugin has no repository configured) | Check the logs and, if it persists, open an issue with the message |
| 501 | Feature not available | "Los plugins pagos todavía no están disponibles (falta el servidor de licencias)" (paid plugins are not available yet: the license server is missing) | There is no fix: paid plugins cannot be installed |
| 502 | NOPAL could not talk to the machine or to an external service | "No se pudo enviar el comando" (could not send the command), "No se pudo mover el eje" (could not move the axis), "No se pudo iniciar el home" (could not start homing), "No se pudo contactar al láser" (could not reach the laser), "No se detectó respuesta GRBL en este puerto" (no GRBL response detected on this port), or an AI provider error | Check that the machine is on, connected and on the same network. See Troubleshooting |
| 503 | NOPAL Intelligence is not available | A clear message that the AI is off | An administrator must turn it on and configure a server |
409 versus 502
A 409 indicates the order could not be applied to the current state (for example, pausing something that is not printing). NOPAL does not always tell that case apart from a communication failure with the machine. A 502 indicates that communication failed while running a command on the machine or an external service.
Printer registration codes
When registering a network printer (Marlin over WiFi, Bambu Lab, Elegoo or FlashForge), a failure answers 400 with detail and an error_code:
error_code | When | What to do |
|---|---|---|
IP_INVALID | The address is not valid | Check the IP or host name |
CREDENTIAL_REJECTED | The printer rejected the credentials | Check the access code, the check code or the printer's details |
SERVICE_REFUSED | The printer refused the connection to the service | Check that the printer's network service is enabled |
CONNECTION_FAILED | There was no connection | Check that the printer is on and on the same network as NOPAL |
PROTOCOL_INVALID | The response does not have the expected format | Verify the address belongs to a printer of that brand |
UNKNOWN | Any other case | Check the logs |
NOPAL does not tell "port blocked" from "device off": they produce the same timeout and cannot be separated without inventing a signal.
For more detail, see Connect your first machine.
Source
The codes and messages come from the core's exceptions (HTTPException) and from backend/errors.py. A particular route may also return codes of its own: see the core REST API.