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
402
Description
Payment required — not enough AI credits to run the requested analysis.
Name
403
Description
Forbidden — you can see the resource but are not allowed to perform this action.
Name
404
Description
Not found — the requested resource does not exist.
Name
409
Description
Conflict — the write would collide with something that already exists.
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
facet_not_found
Description
No facet exists with the given name. Returned by GET /v1/facets/{name} for unknown names. details.available_facets lists every valid facet.
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}), and by /v1/ads/by-share-url for a link that parses but matches nothing.
Name
ad_media_unavailable
Description
The ad exists but its picture or video file does not. Returned by the download endpoints (HTTP 404). Nothing is charged.
Name
ad_media_not_video
Description
media=video was requested for an ad that is not a video. Returned by the download endpoints (HTTP 400).
Name
insufficient_ai_credits
Description
Your AI-credit balance cannot cover the requested ad analysis (HTTP 402). Raised before any work, so nothing is generated and nothing is debited. details carries required, used, total, and remaining. Distinct from quota_exceeded, which is about API request quota.
Name
ai_analysis_not_found
Description
No AI analysis has been generated yet for this ad. Returned by GET /v1/{meta-ads,tiktok-ads,instagram-posts}/{id}/ai-analysis (HTTP 404).
Name
ai_credits_not_provisioned
Description
The API key is not linked to a Brandsearch user, or that user has no AI-credit pool. Returned by GET /v1/ai-credits (HTTP 404).
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 the authenticated user has no access to it (no owner / edit / view grant). Returned by the swipe folder endpoints.
Name
swipe_folder_forbidden
Description
The authenticated user can see the folder (view grant) but is not allowed to perform this action. Returned by the write endpoints — POST /v1/swipe/*-folders/{id}/items, PATCH /v1/swipe/*-folders/{id}, DELETE /v1/swipe/*-folders/{id}/items/{item_id} — when the user needs edit or owner, and by DELETE /v1/swipe/*-folders/{id}, which is owner-only (HTTP 403).
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 and PATCH /v1/swipe/*-folders/{id} (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.