Handling Errors

The Copyleaks API uses standard HTTP response codes to indicate success or failure. Understanding these codes helps you build robust integrations.

HTTP Errors

Our API returns structured error responses with the following error types:

invalid_request_error: Invalid request format, missing parameters, or malformed data.
authentication_error: Authentication failed due to invalid credentials, disabled account, or too many failed login attempts.
payment_error: Payment-related issues including insufficient credits, expired subscriptions, or team billing errors.
api_error: Internal server errors, service overload, timeouts, or temporary unavailability.

Error Response Format

All errors return a consistent JSON structure:

{
  "error": {
    "type": "invalid_request_error",
    "id": "missing_parameter",
    "code": 1,
    "message": "Bad request. One or several required parameters are missing or incorrect.",
    "url": "https://docs.copyleaks.com/using-the-apis/api-errors/#error-reference",
    "details": [
      {
        "param": "labels",
        "message": "Id Label EXAMPLE-v1 is not supported"
      }
    ]
  }
}

The url and details fields are optional and may not be present in all error responses. The details field, when present, contains an array of objects with param and message properties that provide additional context about specific parameters that caused the error.

Error Reference

Code	Type	Error	Message
1	`invalid_request_error`	`missing_parameter`	Bad request. One or several required parameters are missing or incorrect.
2	`authentication_error`	`invalid_credentials`	Invalid login credentials.
3	`authentication_error`	`email_confirmation_required`	To use your account, you need to confirm the email address.
4	`authentication_error`	`user_disabled`	This user is disabled. Contact support for help.
5	`api_error`	`download_failed`	Failed to download the requested URL.
6	`invalid_request_error`	`file_too_large`	Cannot complete the scan request because the file is too large.
7	`invalid_request_error`	`text_read_failed`	Failed reading the submitted text.
8	`invalid_request_error`	`image_quality_too_low`	The image quality is too low to scan.
9	`api_error`	`temporarily_unavailable`	Temporarily unavailable. Please try again later.
10	`invalid_request_error`	`unsupported_file_type`	This file type is not supported.
11	`invalid_request_error`	`not_enough_text`	Not enough text to scan. The minimum text length is 30 characters and at least 6 words.
12	`invalid_request_error`	`document_too_long`	This document is too long (The maximum number of pages allowed is <max-allowed>, while this document contains <number> pages).
13	`payment_error`	`insufficient_credits`	You don’t have enough credits to complete the request (required <number> credits)!
14	`invalid_request_error`	`invalid_file`	The submitted file is invalid.
15	`invalid_request_error`	`invalid_url`	The submitted URL is invalid!
16	`api_error`	`internal_server_error`	The server encountered an internal error or misconfiguration and was unable to complete your request. We are investigating the problem. Ticket ID <00000000-0000-0000-0000-000000000000>.
17	`payment_error`	`no_credits`	You have no credits. You need to purchase credits in order to complete the request.
18	`invalid_request_error`	`copyshield_widget_missing`	Copyshield widget is not showing on your webpage.
19	`invalid_request_error`	`headers_too_long`	’<headers>*’ headers are too long (limited to <max-size> characters together)!
20	`invalid_request_error`	`only_multipart_allowed`	Only MIME multipart content type is allowed!
21	`invalid_request_error`	`single_file_upload_only`	You can upload one file at a time!
22	`invalid_request_error`	`file_size_unknown`	Unable to determine file size.
24	`invalid_request_error`	`bad_filename`	Bad filename!
25	`invalid_request_error`	`undefined_language`	Undefined language!
26	`api_error`	`process_still_running`	The request cannot be completed because the process is still running.
27	`invalid_request_error`	`unknown_process_id`	Unknown process id!
30	`invalid_request_error`	`missing_header`	Missing ‘<name>’ header value!
31	`invalid_request_error`	`bad_parameter`	Bad parameter ‘<param-name>‘!
32	`authentication_error`	`too_many_failed_logins`	Too many failed login attempts. Please try again in <number> hours.
33	`invalid_request_error`	`header_key_too_long`	Http header ‘<headers>’ key is too long (max length is <max-size> characters)!
37	`authentication_error`	`authorization_denied`	Authorization has been denied for this request.
38	`invalid_request_error`	`order_already_activated`	Order has already been activated.
39	`invalid_request_error`	`unsupported_method`	Unsupported method.
40	`payment_error`	`institution_subscription_expired`	Institution subscription has expired.
41	`invalid_request_error`	`file_password_protected`	The submitted file is password protected.
42	`payment_error`	`msg_team_error`	Scan failed due to team error. Please contact your team administrator to solve this issue.
43	`invalid_request_error`	`all_document_excluded`	As a result of your scan settings, this scan failed since the entire document was excluded.
44	`invalid_request_error`	`bad_url`	The submitted url is not valid
45	`api_error`	`failed_to_index`	We were unable to index your file.
46	`invalid_request_error`	`no_repos_or_db_to_index`	As a result of your scan settings, we failed to index your file since copyleaksDb was set to false and the array of repositories was empty.
47	`invalid_request_error`	`unsupported_language`	Language not supported
48	`invalid_request_error`	`image_too_bright`	Image is too bright. Please try another image with less exposure.
49	`invalid_request_error`	`low_dynamic_range`	Image has poor dynamic range. Please try another image with more contrast.
50	`invalid_request_error`	`image_textureless`	Image appears blank or textureless. Please upload a different image.
51	`invalid_request_error`	`image_blurry`	Image is too blurry. Please upload a sharper image.
52	`invalid_request_error`	`insufficient_colors`	Image has too few colors. Please upload a more detailed image.
53	`invalid_request_error`	`image_truncated`	Image file is incomplete or corrupted. Please upload a complete image file.
54	`api_error`	`rate_limit_exceeded`	Too many requests have been received from your IP address recently. Please wait a moment and then try your request again.
55	`api_error`	`site_is_overloaded`	Site is overloaded.
56	`invalid_request_error`	`unsupported_lang`	Language not supported.
57	`api_error`	`request_timed_out`	The request has timed out.
58	`invalid_request_error`	`empty_text`	Text is empty.
59	`invalid_request_error`	`unsupported_image_format`	Image format not supported. Please upload a <supported_formats> image.
60	`invalid_request_error`	`image_load_failed`	Unable to process the image. Please try uploading again.
61	`invalid_request_error`	`image_too_small`	Image is too small. Please upload an image at least <min_width>x<min_height> pixels.
62	`invalid_request_error`	`image_too_large`	Image is too large. Please upload an image up to <max_megapixels> megapixels (e.g., <example_dimensions>).
63	`invalid_request_error`	`unsupported_aspect_ratio`	Image aspect ratio <aspect_ratio> not supported. Please upload an image with a standard aspect ratio.
64	`invalid_request_error`	`image_too_dark`	Image is too dark. Please try another image with better lighting.

Get started

Guides

Using the APIs

Concepts

Resources

HTTP Errors

Error Response Format

Error Reference

​HTTP Errors

​Error Response Format

​Error Reference

HTTP Errors

Error Response Format

Error Reference