What Are the Most Common API Error Codes and What Do They Mean?

When you work with the BrandMentions API, you will sometimes see error codes in the JSON response.

Each error code has a specific meaning and usually points to something easy to fix, such as a missing parameter, invalid value, or an account limit.

Most common BrandMentions API error codes

Every error is returned as a JSON response that includes:

status – usually error
code – numeric error code
message – short description

Example shape:

{   "status": "error",   "code": 3,   "message": "Missing API key" }

Below are the most useful codes to know while you integrate and debug.

1. Request and authentication errors

These errors mean the API request itself is not formed correctly or is not authenticated.

Code	Message	What it means	How to fix it
1	Missing command	The `command` parameter is not present in the URL.	Add `&command=SomeCommand` to your request, for example `&command=GetRemainingCredits`.
2	Invalid command	The `command` value does not match any known BrandMentions API command.	Check the documentation and spelling. Use valid commands such as `PostSearch`, `GetMentions`, `GetProjectMentions`, and so on.
3	Missing API key	The `api_key` parameter is not present in the request.	Add `&api_key=YOUR_API_KEY` to the URL. Make sure you are using the key provided by the BrandMentions team.
4	Invalid API key	The `api_key` is present but is not valid for any account.	Check for typos, whitespace, or outdated keys. If needed, ask the team to resend or regenerate your key.
6	Unknown error	A general internal error that does not match a specific code.	Retry later, and if it persists, log the full response and contact support.
8	Unexpected error	Another generic error for unexpected conditions.	Handle as a transient error. Log details and, if needed, contact support with the request info.

2. Search job and hash related errors

These appear when you work with PostSearch, GetMentions, or GetProcessedMentions.

Code	Message	What it means	How to fix it
7	Search not ready	You called `GetMentions` or `GetProcessedMentions` before the search job has finished.	Wait until the search is complete. Use `callback` with `PostSearch` or poll `GetProcessedMentions` until `processing_ended` is `true`.
9	Invalid search hash	The `search_hash` value is missing, expired, or does not match any active search job.	Confirm you are using the exact `search_hash` returned by `PostSearch` and that you are within the one hour validity window.
12	Invalid time range	A time related parameter (for example `time_range` in `PostSearch`) is invalid.	Use documented values such as `hour`, `day`, `week`, `month` for `time_range` or correct your date formats.
39	Invalid start period	`start_period` is missing or not a valid date or date time.	Use a valid date or `YYYY-MM-DD HH:MM:SS` format for project based endpoints.
40	Invalid end period	`end_period` is missing or invalid.	Same as above. Ensure the value is a valid date or date time.
41	Invalid period	The combination of start and end period is invalid.	Ensure `start_period` and `end_period` are valid and consistent and that start is not after end.

3. Keyword and filter validation errors

These errors indicate that something about your keywords, languages, countries, or filters does not respect the documented rules.

Code	Message	What it means	How to fix it
10	Missing keywords	You did not provide any `keyword1...keyword5` or boolean expression where required.	Add at least one valid keyword or a boolean expression, depending on the endpoint.
11	Empty keywords	A keyword parameter exists but is empty or consists only of whitespace.	Ensure each keyword has at least 3 characters, as required by the API.
23	Too many keywords	More than 5 main keywords were sent.	Limit keywords to `keyword1` through `keyword5`. Consolidate or use boolean logic if needed.
24	Too short keyword	One of the keywords is shorter than 3 characters.	Use longer keywords that respect the 3 to 50 characters rule.
26	Too long keyword	A keyword is longer than 50 characters.	Shorten the keyword or split it into multiple terms and use required keywords if needed.
27	Too many required keywods	Too many required terms were added for a specific keyword.	Reduce the number of required terms in `required_keywordsX[]`.
28	Too short required keyword	A required keyword is too short.	Increase its length to respect minimum requirements.
29	Too long required keyword	A required keyword is too long.	Shorten it to stay within the allowed length.
30	Too many excluded keywords	Too many excluded terms were added.	Reduce the number of `excluded_keywordsX[]` values.
31	Too short excluded keyword	An excluded keyword is too short.	Increase the length.
32	Too long excluded keyword	An excluded keyword is too long.	Shorten it.
33	Too many excluded domains	You provided too many `excluded_domains`.	Trim the list of excluded domains.
34	Too short excluded domain	An excluded domain string is too short.	Provide complete domain names.
35	Too long excluded domain	An excluded domain string is too long.	Use shorter domain values.
12	Invalid time range	`time_range` has a value outside the allowed ones.	Use `hour`, `day`, `week`, or `month`.
13	Invalid language	A language code is not valid.	Use two character language codes as specified in the docs, for example `en`.
14	Invalid country	A country code is not valid.	Use allowed 2 letter codes or `ALL` as documented for country filters.
36	Invalid sources	A value in `active_sources[]` or `sources[]` is not allowed.	Use only documented source values such as `web`, `facebook`, `twitter`, `instagram`, `linkedin`, `reddit`, `youtube`, `tiktok`, `bluesky`.
37	Invalid quality filter	`quality_filter` has an unsupported value.	Use empty (default) or non empty values like `1` to enable curation, as described in the `AddProject` documentation.
38	Invalid linked value	The `linked` filter has an invalid value.	Use values expected by the docs, typically `0` or `1` or similar documented options.
77	Invalid excluded language	A language code in `excluded_languages[]` is invalid.	Use valid language codes.
78	Invalid excluded country	A country code in `excluded_countries[]` is invalid.	Use valid country codes.

4. Project related errors

These errors occur when you create, edit, list, or delete projects.

Code	Message	What it means	How to fix it
15	Failed adding project	Something went wrong while creating a project.	Check all parameters (keywords, countries, sources). If they look correct, contact support with the full request.
17	Reached total projects limit	You reached the maximum number of projects allowed for your account.	Delete unused projects or upgrade your plan to allow more projects.
18	Missing project ID	A command that requires `project_id` did not receive it.	Add `project_id` to the request, for example `&project_id=1`.
19	Invalid project ID	The `project_id` does not match any project in your account.	Use `ListProjects` to confirm valid project IDs and update your code accordingly.
20	Missing page	A command that needs `page` was called without it.	Provide the `page` parameter when required or rely on default if the docs allow it.
21	Invalid page	The `page` value is invalid (for example negative or not a number).	Use positive integers starting from 1.
45	Missing mentions per page	`per_page` is missing where required.	Provide `per_page` or let the default apply if the endpoint allows omitting it.
46	Invalid mentions per page	`per_page` has an invalid value, such as `0` or more than `100`.	Use values between 1 and 100.
47	Project delete error	An error occurred while attempting to delete a project.	Try again or contact support if the problem persists.
48	Project delete failed	The project could not be deleted.	Verify the `project_id` and check for account restrictions. Contact support if needed.
70	Failed updating project	An error occurred while editing the project.	Check edit parameters and retry. If it keeps failing, contact support.
74	Missing editable project parameters	You called `EditProject` without any valid fields to edit.	Provide at least one editable field (for example keywords, boolean expression, sources) as shown in the docs.
75	Missing project editing type	Edit type is missing.	Provide a valid editing type parameter as documented.
76	Invalid project editing type	The provided editing type is not allowed.	Use only the edit types documented for `EditProject`.

5. Limits, abuse, and historical data errors

These codes are strongly related to usage quotas and safety rules.

Code	Message	What it means	How to fix it
5	Limits reached	You hit an account limit. This can be related to credits, number of projects, or similar limits.	Call `GetRemainingCredits` to inspect your remaining credits and consider upgrading or reducing usage.
56	Abusive behavior detected	The API detected usage that violates rate or usage policies.	Reduce request frequency, implement backoff, avoid large bursts, and review your usage pattern.
59	Reached total keywords limit	Your account reached the allowed number of keywords.	Remove unused keywords or upgrade your plan to increase the limit.
60	Historical data already run for selected period	`RunProjectHistorical` was called for a period already processed.	Adjust the `period` or the project configuration. Avoid calling historical runs for the same period again.
65	Reached total review sources limit	The account reached the limit of review sources per project or account.	Remove existing review sources or upgrade to a plan with higher limits.

6. Boolean search and expression errors

BrandMentions supports boolean expressions in some project operations. These codes help you debug issues related to that feature.

Code	Message	What it means	How to fix it
61	Invalid keyword match type	`match_type` has a value outside `exact`, `broad`, or `case_sensitive`.	Use one of the valid match types.
62	Both keywords and boolean expression not allowed	You provided both main keywords and a boolean expression where only one is allowed.	Choose one strategy. Either use simple keywords or a boolean expression, not both.
63	Missing keywords and boolean expression	Neither keywords nor a boolean expression were provided where one is required.	Provide at least one keyword or a valid boolean expression.
64	Invalid boolean expression	The boolean expression could not be parsed or is invalid.	Review the expression syntax. Check parentheses, operators like `AND`, `OR`, `NOT`, and quotes.
68	Missing boolean expression	The call requires a boolean expression but none was supplied.	Add the `boolean_expression` parameter and URL encode it.
69	Not boolean search project	You attempted a boolean related operation on a project that is not configured for boolean search.	Ensure that the project was created with a boolean expression or adjust your API call.