MagicINFO REST API error codes: what they really mean

MagicINFO returns API errors as JSON with a six-digit errorCode whose first three digits follow the HTTP status (400…, 401…, 404…, 500…), but several of the messages point in the wrong direction. The table below lists the codes we have met and what actually caused them.

How an error looks

{"url":"/MagicInfo/restapi/v2.0/…","errorCode":"400002","errorMessage":"[field] Not allowed value.","errorDetails":null}

• errorCode is a string, so compare it as "400009", not as a number.
• Validation errors (400002 and friends) go to the caller only and never reach MagicINFO's logs. Save the response body; errorMessage often names the field at fault.

Code table

Code	What it means	Real causes we have seen
400001	A required value is missing	Wrong field name. For example, the live-status request tickets expect ids, not deviceIds, and deleting a playlist needs a deleteMethod.
400002	A value is invalid	The field is named in the message. A common one is [frame.lineData] Not allowed value. when saving schedules, see "Failed to save the data". Creating a schedule without its folder id or resolution also lands here.
400009	The name already exists	Creating an organisation, role or content list under a name that is already taken.
400501	LFD content in a multi-frame schedule	A layout (LFD) file needs a single-frame schedule. Declare the frame as fixed and single-frame (ZERO_FRAME_ONLY).
400630	Device does not fit the target group	The device type is not accepted by the group you are approving or moving it into. Choose a compatible group.
401000, 401002, 401010	Sign-in not accepted	Wrong user ID or password. A stored password that had drifted from the real one showed up as 401000 and looked like an API fault.
401003	Access token expired	The short-lived token lasts 30 minutes. Sign in again, or use the refresh token, see sign in with TOTP.
401004	Refresh token expired	After 7 days. Sign in again.
401005	Token is invalid	The token could not be read; it was not revoked. Usual causes: a Bearer prefix, quotes, a byte-order mark or line ending added by a script, a truncated or stale value, or the outdated id / otpValue sign-in body.
401006	Refresh token is invalid	Same checks as 401005, for the refresh token.
401007	Account locked	Too many failed passwords or authenticator codes. Stop retrying; an administrator must unlock the account.
401008	Account not approved	A self-registered user is waiting for an administrator.
401009	Session idle timeout	The token was unused for too long. Sign in again.
401011	Two-step enrolment required	A new account's first sign-in, not a permissions problem. Finish enrolment with one sign-in that includes a totp code.
401013	Authenticator code rejected	The code was expired or wrong. Wait for the next 30-second window and retry once.
404001	Not found	The referenced object (program, frame list, device record and so on) does not exist. Thumbnails return it as "The file path is not found." when the image file is missing.
500000	Internal error	Often extra or unknown body fields, for example a playlist created with creator or version ids. Send only the minimal fields.
500003	Labelled "SQL Error"	Frequently not SQL at all. Causes: a password that breaks the policy when creating a user, a missing numeric groupId, or a JSON body sent to an endpoint that expects query parameters. See Error 500003.
500013	Content file upload failed	LFD and URL content sent to the normal file-upload endpoint. URL content has its own endpoint (/cms/contents/url-settings).

Surprising HTTP statuses without a special code

• HTTP 503 on a password reset: the user's organisation has no SMTP settings. See Password-reset e-mail not arriving. HTTP 404 on the same call means the user ID, name and e-mail did not match.
• HTTP 500 from the connection check (POST /rms/devices/connections-checked): this happens whenever any device in the batch is not reachable. The body is still complete, with successList and failList, so parse it instead of treating the call as failed. Standby, offline and unknown devices all land in failList without a reason.

Tips that save time

• Log the full response body, not just the status. Validation messages exist only there.
• In Windows PowerShell 5.1, piping a one-element array into ConvertTo-Json turns it into a plain object. Endpoints that expect a JSON array then fail. Use ConvertTo-Json -InputObject $array instead.
• Retry only 401, and only once, after a fresh sign-in. Failed sign-ins and rejected codes count towards the account lockout.

Related

• MagicINFO REST API: sign in with TOTP
• Error 500003 when creating a user
• "Failed to save the data" when saving a schedule
• "An unexpected error has occurred" at sign-in

Compiled from our own work with MagicINFO Server 21.1070, October 2026. Codes can change between server builds; for unlisted codes, start from errorMessage and the HTTP status.