 | This page is part of theMediaWiki Action API documentation. |
| MediaWiki Action API |
|---|
| Basics |
| Authentication |
| Accounts and Users |
| Page Operations |
|
| Search |
| Developer Utilities |
| Tutorials |
| v · d · e |
If something goes wrong in an API request, an error or a warning will be thrown (although the HTTP response will usually still be200 OK).Warnings are thrown for non-fatal conditions such as invalid parameters, whereas errors are only thrown for fatal conditions.
Warnings are grouped by the name of the module that caused them.Multiple warnings from the same module are separated by a newline.In the legacy error formatting mode (see below), which is the default, warnings are output in the following format:
"warnings":{"modulename":{"*":"warning text"}}
(* will be replaced bywarnings whenformatversion=2 is used.)
When a non-legacy error formatting option is used, warnings are output in the same format as errors.E.g. witherrorformat=wikitext the format will be:
"warnings":[{"code":"warning message key","*":"text of warning","module":"API module which caused the warning"}]
(* will be replaced withtext whenformatversion=2 is used.)
| Type | Description | Warning message(s) |
|---|---|---|
| Disabled submodule | Theaction=query submodule has beendisabled in the wiki. To check if a module is available before invoking it, seeHow do I check if an API module is available? in the FAQ. | Thesubmodulename module has been disabled. |
| Missing submodule | Thelist,prop ormeta submodule is not present in the wiki, for example if it is implemented by an extension that isn't loaded. | Unrecognized value for parameterlist=submodule:value. |
| Parameter validation | Warnings thrown when validating parameters of any API module.paramname is replaced by the name of the parameter. |
|
Since MediaWiki 1.29 errors are localizable, and available in multiple formats.An error (or warning) is expected to consist of amessage, an error code (an arbitrary string, usually generated from the message key; see also#Standard error messages below), and optional extra data (an associative array).An API response with errors will look like this:
{"errors":[{"code":"error-code",/* ...error message..., */"data":[/* ...any extra data... */],"module":"path to the API module that generated the error"},/* ...more errors... */],"docref":"human-readable message on where to find help"}
Thedata key in the output above will be missing if there is no extra data to display.
The way the error message in the output above is returned to the client is controlled by theerrorformat API parameter.The various error formats available are:
| Format | Description | Output |
|---|---|---|
| html | Intended for human display in HTML-capable clients. MediaWiki will ensure that the HTML is safe; it is just as trustworthy as article content (both are parsed Wikitext). | "html":"the message, interpreted as wikitext and parsed into HTML" |
| wikitext | "text":"the message as-is, with parameter substitution but without any parsing" | |
| plaintext | Intended for human display in HTML-incapable clients. Plaintext conversion is a minimal, best-effort transformation to make the message (assumed to contain wikitext) more readable: tags are removed, HTML entities are replaced, certain HTML tags are intelligently replaced with punctuation. | "text":"the message, like wikitext, but with added plaintext conversion" |
| raw | Intended as a machine-readable format (note that the error key is more unique than the error code). Parameters can themselves be objects withkey andparams fields. | "key":"message key","params":[/* ...message parameters... */] |
| none | No message information at all. | |
| bc | The default, forbackwardcompatibility. There’s no point in specifying this value, use one of the non-legacy formats instead. | See#Legacy format |
For the formatting modes which involve message lookup (html,wikitext andplaintext) the API parametererrorlang can be used to set the language (only needed when different from the content language) anderrorsuselocal to set whether the MediaWiki: namespace can be used to override default error messages.
Error codes are also returned in theMediaWiki-API-Error response HTTP header, separated by commas when there are multiple errors.
For an example error response or to test your client's error handling, visithttps://en.wikipedia.org/w/api.php?action=blah&errorformat=plaintext&format=jsonfm&formatversion=2
API responses can contain multiple errors.For an example, try adding the linesthe abusefilter will block this
andthe abusefilter will also block this
to a Test Wikipedia page asAPI sandbox(if you are logged in, go to the action=edit tab and clickAuto-fill the token
first before making the request).
Whenerrorformat is not set (or set tobc), errors will be displayed in the legacy format instead.
In the legacy error format, there is always at most one error; additional ones are discarded.The response looks like this:
{"error":{"code":"error-code","info":"the message as-is, with parameter substitution but without any parsing",/* ...any extra data... */}}
The extra data in the output above is spliced into the object instead of being under thedata key.
Error messages are documented in this wiki as shown below, which corresponds to the json error response in#Legacy format above:
| Code | Info |
|---|---|
| errorcode | error message |
The various error messages are:
| Type | Description | Error message(s) | |
|---|---|---|---|
| Code | Info | ||
| Disabled module | The action module has beendisabled in the wiki. To check if a module is available before invoking it, seeHow do I check if an API module is available? in the FAQ. | moduledisabled | Themodulename module has been disabled. |
| Missing module | The action module is not present in the wiki, for example if it is implemented by an extension that isn't loaded | unknown_action | Unrecognized value for parameteraction:modulename. |
| Parameter validation | Errors thrown when validating parameters of any API module.paramname is replaced by the name of the parameter. | multival_paramname | Only one of 'paramname' is allowed for parameter'value1', 'value2', 'value3'. |
| unknown_paramname | Unrecognized value for parameterparamname:value. | ||
| paramname | paramname may not be less thanmin (set tovalue). | ||
| paramname | paramname may not be overmax (set tovalue) for bots or sysops. | ||
| paramname | paramname may not be overmax (set tovalue) for users. | ||
| badtimestamp_paramname | Invalid value "value" for timestamp parameterparamname. | ||
| baduser_paramname | Invalid value "value" for user parameterparamname. | ||
| invalidparammix | The parametersparam1,param2,param3 can not be used together. | ||
| missingparam-one-of | One of the parametersparam1,param2,param3 is required. | ||
| _badcontinue | Invalid continue param. You should pass the original value returned by the previous query. | ||
Some generic error messages are shared among modules.If a module can throw these errors, that's explicitly mentioned in itsPossible errors section.
| Code | Info |
|---|---|
| unknownerror | Unknown error: This usually means something crazy like a rare race condition occurred. If you get this error, retry your request until it succeeds or returns a more informative error message |
| unknownerror | Unknown error: "errorcode". |
| unknownerror-nocode | Unknown error. |
| unsupportednamespace | Pages in the Special namespace can't be edited |
| protectednamespace-interface | You're not allowed to edit interface messages |
| protectednamespace | You're not allowed to edit pages in the "namespace" namespace |
| customcssjsprotected | You're not allowed to edit custom CSS and JavaScript pages |
| cascadeprotected | This page is fully protected because it is included in the following pages, which are fully protected with the "cascading" option turned on: list of cascade-protected pages |
| protectedpage | The "right" right is required to edit this page |
| permissiondenied | Permission denied. |
| confirmemail | You must confirm your email address before editing pages. Please set and validate your email address through youruser preferences. |
| blocked | You have been blocked from editing. |
| autoblocked | Your IP address has been blocked automatically, because it was used by a blocked user. |
| ratelimited | You've exceeded your rate limit. Please wait some time and try again. |
| readonly | The wiki is currently in read-only mode. |
| badtoken | Invalid token (did you remember tourlencode it?) |
| missingtitle | The page you requested doesn't exist |
| mustbeposted | Type of your HTTP request message must be POST |
| hookaborted | The modification you tried to make was aborted by an extension hook |
| nosuchpageid | There is no page with IDid |
| nosuchrevid | There is no revision with IDid |
| nosuchrcid | There is no change with rcid "id" |
| nosuchuser | The user you specified doesn't exist |
| invalidtitle | Bad title "title" |
| invaliduser | Invalid username "username" |
| assertbotfailed | "assert=bot" has been used, but logged in user is not a bot |
| assertuserfailed | "assert=user" has been used, but user is not logged in |
| readapidenied | You need read permission to use this module |
| noapiwrite | Editing of this wiki through the API is disabled. Make sure the$wgEnableWriteAPI=true; statement is included in the wiki's LocalSettings.php file |
format=json&formatversion=2. Forformatversion=1, the fielddocref will be replaced by*.