Request restrictions and typical errors returned by the uCoz API
No more than 10,000 requests per hour are allowed for a single API token on one site.
REQUESTS_LIMIT.
Some modules have additional restrictions. See the uCoz limits page for per-module details.
Entry creation requests (POST) in the Site news, Blog, Publisher, Site directory, Ad board, File catalog, Online games, FAQ, Photo album, and Video modules are counted together for the whole site — across all these modules, regardless of API token or IP address — in a sliding 60-minute window:
Entry edits (PUT) are not counted. This limit is separate from the per-token request limit described above.
Requests from the site owner, administrators, and module editors are counted separately from requests from other users — visitors and ordinary registered users, including requests made with their API tokens. Other users' activity never prevents the owner, administrators, and editors from creating entries. Other users' requests get HTTP 429 with the AUTOPOST_RATE_LIMIT error as soon as the site's total number of creation requests for the hour, including those of the owner, administrators, and editors, reaches the limit.
When a request from the owner, an administrator, or an editor exceeds the limit, the entry is not created and a 60-second warning period starts. Creation requests get HTTP 429 with the AUTOPOST_RATE_LIMIT error, the Retry-After header — the number of seconds until a slot for a new entry frees up (at least until the warning period ends) — and the Cache-Control: no-store header.
When many creation requests run concurrently on one site, the API may also return HTTP 429 with the AUTOPOST_RATE_LIMIT error and a short Retry-After (a few seconds). Always wait for the time in Retry-After before retrying.
Retry-After while the hourly limit is used up, the site is blocked for automatic posting, and entry creation requests get HTTP 403 with the AUTOPOST_BANNED error. Only support can lift the block. Requests from other users never block the site. A client that waits for Retry-After is not blocked: honor this header and spread publishing over time.
The AUTOPOST_BANNED error is returned only when the site is blocked under this rule. If support blocked the site for another reason, the module returns its usual error.
Error messages are returned in the following format:
{"error":{"msg":"Error message","code":"Error code"}}For uAPI (Bearer) validation errors, the response body may also include a numeric num field — the specific reason number when code is VALIDATION_ERROR:
{"error":{"msg":"…","code":"VALIDATION_ERROR","num":2}}The API key was not found or is incorrect. The provided API key does not exist in the system. This usually means the key was mistyped, deleted, or a non-existent value is being used.
The API key exists but is disabled. The key was found in the system but is inactive and cannot be used to execute requests.
You are requesting a URL that does not support the HTTP method used (GET, POST, DELETE, or PUT).
To fix this error, open the module settings in the site Control Panel (/admin) and enable “Enable uAPI for module”.
Your token is temporarily blocked: the hourly request limit was reached. See uAPI limits for details.
HTTP 429 Too Many Requests: the site's hourly limit on entry creation requests was exceeded, or too many creation requests are running concurrently on the site, and the entry was not created.
Retry no earlier than the number of seconds in the Retry-After header.
If requests with an owner, administrator, or editor API token continue without waiting after the warning period, the site will be blocked for automatic posting.
See Entry creation limit for details.
HTTP 403 Forbidden: the site is blocked for automatic posting because entry creation requests with an owner, administrator, or editor API token continued after the warning period without waiting for Retry-After.
This error is returned only when the site is blocked under this rule: if support blocked the site for another reason, the module returns its usual error.
Contact support to unblock it. See Entry creation limit for details.
The request does not include all required parameters. The list for each method is given in the uAPI documentation.
The request was rejected because data does not match module rules. The response includes a num
field with the specific reason number (see the response schema in Swagger for the corresponding method).
Pages module (POST /pages, PUT /pages): num: 2 —
when owntmpl=1, a non-empty custom template body (tmpl) was sent, but the markup is missing the required $POWERED_BY$ placeholder.
See the tmpl field description on the Pages module documentation page.
Codes FM_* come from the File Manager API. The HTTP status below applies when the error fails the whole request. In a batch results[] item the same code and msg are used, but HTTP stays 200. If the API adds a detail, it is appended to msg after a colon.
The path is empty where that is forbidden, contains illegal characters, is too long, or the operation has no effect (source equals destination, or the target is the site root).
The file or folder name does not match the rules: a file must have an extension, a folder name cannot contain a dot, and a leaf name cannot contain slashes.
The download URL does not start with http:// or https://, or it has no file name with an extension.
The name is longer than the site limit (see limits.file_name_max_len and limits.dir_name_max_len from GET /files/quota).
The folder path has more segments than limits.folder_depth.
The folder already has the maximum number of visible objects (limits.files_per_dir).
The extension is on the blocked list (for example executable scripts). Current list: limits.forbidden_ext.
The extension is also blocked on the free plan. List: limits.forbidden_ext_free_plan.
Forbidden content was found in the text. A block-code detail may be appended to msg.
A file or folder with this name already exists. The API does not overwrite existing files on upload or rename.
The name is reserved by the system (see limits.reserved_root_names).
A site page already uses this address. Choose a different folder name.
The object was not found, or the path is inside a reserved tree.
The parent folder does not exist. There is no recursive mkdir.
Write access to this path is denied (for example the read-only folders _fr and graffiti).
Uploading is disabled for this site. Check upload_enabled in GET /files/quota.
Not enough disk space or file slots. msg may include the detail no_space or too_many_files.
The multipart request has no file field.
The file is 1 byte or smaller.
The file is larger than limits.max_file_size (when that limit is set).
One POST /files/upload has more files than limits.max_files_per_upload.
The remote file could not be downloaded (10-second timeout or a network error).
A file was expected, but the path is empty or points to a folder.
A folder was expected, but the path points to a file.
The extension is not in limits.text_ext. The content methods do not read binary files.
The file on disk is larger than limits.edit_max_length bytes. The API does not truncate content.
The content string is longer than limits.edit_max_length characters.
The site root cannot be deleted.
A folder cannot be moved into itself or into one of its descendants.
A required parameter is missing. The parameter name is appended to msg.
An internal error occurred (for example the folder could not be read, or quota accounting is unavailable). Unknown internal codes are also replaced with this one.
The request has no valid site-owner Bearer token.
The token belongs to a different account, not the owner of this site.
You are using an invalid Consumer Key. Check it on the
uAPI panel page.
Signature generation failed. Possible causes: incorrect Token secret;
wrong parameter sorting when building the signature; missing
urlencode or base64 step.
You are using a token that does not exist. To create a token, go to the uAPI panel.
The nonce value you sent was already used.
nonce must be unique for each request.
Possible causes: you are using a uID user token that was deleted, or the uID.me authorization service is temporarily unavailable.
Invalid verification code. The code is issued after you confirm app access to your data in the application. The issue is often caused by copying the code incorrectly from the browser address bar.
In the signed request, oauth_version (or another OAuth parameter) appears more than once.
Each OAuth parameter must appear only once in the request.
If you believe the error is incorrect, contact us via the Feedback form or in the uAPI Telegram community.
Please include in your message:
This will help us investigate faster and provide an accurate answer.