Errors

In this guide, we will talk about what happens when something goes wrong while you work with the API. Let's look at the status codes and error types you might encounter.

You can tell if your request was successful by checking the status code when receiving an API response. If a response comes back unsuccessful, you can use the code and message fields to figure out what went wrong.

Error response format

All errors follow a consistent format with a top-level error object containing a machine-readable code, a human-readable message, and optional details.

Error response

{
  "error": {
    "code": "brand_not_found",
    "message": "No brand found with the given identifier.",
    "details": {}
  }
}

Status codes

Name
200
Description
The request was successful.
Name
400
Description
Bad request — invalid parameters or validation error.
Name
401
Description
Unauthorized — missing or invalid API key.
Name
404
Description
Not found — the requested resource does not exist.
Name
429
Description
Too many requests — rate limit or quota exceeded.
Name
500
Description
Internal server error.
Name
503
Description
Service temporarily unavailable.

Error codes

Name
invalid_api_key
Description
The provided API key is missing or invalid.
Name
revoked_api_key
Description
The API key has been revoked.
Name
rate_limited
Description
You've exceeded the rate limit. Check the Retry-After header and details.retry_after for when to retry.
Name
quota_exceeded
Description
You've exceeded your daily or monthly quota. details.quota_type indicates which limit was hit.
Name
invalid_parameter
Description
A query parameter has an invalid value. details.parameter tells you which one.
Name
validation_error
Description
One or more parameters failed validation. details.errors contains field-level messages. Also returned when search/query endpoints receive an unknown field — common typos surface as validation_error with the offending key at details.parameter (e.g., niches → niche, country → country_code, language → languages, brand_id → brand_ids).
Name
brand_not_found
Description
No brand exists with the given ID or URL.
Name
ad_not_found
Description
No ad/post exists with the given ID. Returned by the detail endpoints (/v1/meta-ads/{ad_id}, /v1/tiktok-ads/{ad_id}, /v1/instagram-posts/{post_id}).
Name
user_not_found
Description
Returned by /v1/me and /v1/usage if the user record for your API key no longer exists.
Name
swipe_not_provisioned
Description
Returned by /v1/swipe/* endpoints when the API key's account has not been linked to a Brandsearch user. (HTTP 403.)
Name
swipe_folder_not_found
Description
Folder does not exist or is not owned by the authenticated user. Returned by the swipe folder endpoints.
Name
swipe_folder_name_taken
Description
A folder of the same type with the same name already exists for this user. Returned by POST /v1/swipe/*-folders (HTTP 409). details.folder_type and details.name identify the conflict.
Name
swipe_folder_quota_exceeded
Description
The user has reached the per-type folder cap. Returned by POST /v1/swipe/*-folders (HTTP 429). details.current is the count of existing folders of this type, details.limit is the cap.
Name
swipe_item_quota_exceeded
Description
The user has reached the per-type saved-item cap. Returned by POST /v1/swipe/*-folders/{folder_id}/items (HTTP 429). details.item_type is ads or spectre, details.current is the count of existing saved items, details.limit is the cap. Adding an already-saved item to another folder does NOT consume this quota.
Name
swipe_board_not_found
Description
Board does not exist or is not owned by the authenticated user. Returned by /v1/swipe/boards/{board_id}.
Name
service_unavailable
Description
The service is temporarily unavailable. Try again shortly.
Name
internal_error
Description
An unexpected error occurred on our end.

Rate limit error

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded.",
    "details": {
      "retry_after": 12,
      "window": "1m"
    }
  }
}

Validation error

{
  "error": {
    "code": "validation_error",
    "message": "One or more parameters are invalid.",
    "details": {
      "errors": [
        {
          "field": "sort_by",
          "message": "Invalid sort field"
        }
      ]
    }
  }
}

Quota exceeded error

{
  "error": {
    "code": "quota_exceeded",
    "message": "Daily quota exceeded.",
    "details": {
      "quota_type": "daily",
      "limit": 500
    }
  }
}

Error codes were uppercase (BRAND_NOT_FOUND) in versions ≤0.3.0 and changed to lowercase snake_case (brand_not_found) in 1.0.0. HTTP status codes, error messages, and the details shape are unchanged.