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"
      }
    ]
  }
}

Note: 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.