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, a revoked key, or a key whose account is no longer active.

  • 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, or your account is in a state that blocks it.

  • Name
    422
    Description

    Unprocessable — the request is valid, but this item cannot be handled that way (for example, transcribing an image ad).

  • Name
    429
    Description

    Too many requests — rate limit or quota exceeded.

  • Name
    500
    Description

    Internal server error.

  • Name
    502
    Description

    Bad gateway — a service the request relies on returned an error. Try again later.

  • 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 can no longer be used. Either the key itself has been revoked, and you need a new one, or the account it belongs to is no longer active (for a teammate, the team leader's account), and the key works again once the account is reactivated. message says which. See Authentication.

  • Name
    rate_limited
    Description

    You've exceeded the rate limit. Check the Retry-After header and details.retry_after for when to retry. The per-IP limit also counts requests with a missing, invalid or revoked key, so repeated rejected requests can end in this error rather than a 401.

  • 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, or email 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}, /v1/emails/{email_id}), by the download, AI analysis, and transcription endpoints, 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, or the email exists but its screenshot 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, or for an email. Returned by the download endpoints (HTTP 400).

  • Name
    product_not_found
    Description

    No product exists with the given ID or URL. Returned by GET /v1/products/{product_id}, GET /v1/products/by-url and the product image (HTTP 404). The message is the same whatever the reason, and nothing is charged.

  • Name
    media_unavailable
    Description

    The product exists but we do not hold its image. Returned by GET /v1/products/{product_id}/image (HTTP 404). Nothing is charged.

  • Name
    audience_unavailable
    Description

    The product exists but its market's ads disclosed no reach, so there is no audience to describe. Returned by GET /v1/products/{product_id}/audience (HTTP 404). Nothing is charged.

  • Name
    insights_unavailable
    Description

    The product exists but none of its market's ads has been analysed yet, or the analyses have no value to show. Returned by GET /v1/products/{product_id}/creative-insights (HTTP 404). Nothing is charged.

  • Name
    sourcing_unavailable
    Description

    The product exists but no supplier was matched to it; its sourcing_available is false. Returned by GET /v1/products/{product_id}/sourcing (HTTP 404). Nothing is charged.

  • Name
    market_not_found
    Description

    No product belongs to the given market. Returned by GET /v1/markets/{market_id} (HTTP 404). Nothing is charged.

  • 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 or email. Returned by GET /v1/{meta-ads,tiktok-ads,instagram-posts,emails}/{id}/ai-analysis (HTTP 404).

  • Name
    ad_not_video
    Description

    The ad is an image, so it has no audio to transcribe. Returned by GET and POST /v1/meta-ads/{ad_id}/transcription (HTTP 422).

  • Name
    transcript_not_found
    Description

    No transcript exists for this ad yet. Returned by GET /v1/meta-ads/{ad_id}/transcription (HTTP 404). POST to the same path to produce one.

  • Name
    transcript_unavailable
    Description

    This ad cannot be transcribed, and there is no existing transcript to return. Returned by POST /v1/meta-ads/{ad_id}/transcription (HTTP 422).

  • Name
    transcription_failed
    Description

    The transcription service returned an error. Returned by POST /v1/meta-ads/{ad_id}/transcription (HTTP 502). No credit is charged; try again later.

  • 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
    account_link_broken
    Description

    Your account is linked to a Brandsearch user that no longer exists, so its swipe folders cannot be reached. Returned when creating a folder (POST /v1/swipe/*-folders, HTTP 409), and by every mobile feed endpoint. Nothing has been deleted, but retrying will not help until the link is repaired: reconnect the Brandsearch MCP connector, or create an API key in the dashboard. Contact support if it persists.

  • 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}, and by POST and PATCH on mobile feed 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 and POST /v1/swipe/mobile-feed/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
    plan_required
    Description

    The plan does not include this feature. Returned by the mobile feed folder endpoints (listing, reading, creating, renaming and deleting folders, and filing a post in a folder or taking it out) on a trial, a cancelled plan, or no paid plan (HTTP 403). Listing, reading and removing posts work on any plan. details.feature names the feature (mobile_feed).

  • Name
    feature_not_available
    Description

    The feature is in early access and not open to this account yet. Returned by the mobile feed endpoints when Facebook is asked for by an account without Facebook access (HTTP 403). details.feature names it (mobile_feed_facebook).

  • Name
    mobile_feed_post_not_found
    Description

    The post is not in the user's mobile feed, whether or not it exists (HTTP 404). details.post_id repeats the id.

  • Name
    mobile_feed_write_conflict
    Description

    A mobile feed post kept changing while it was being saved (HTTP 409). Nothing was lost; send the request again.

  • 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.

Was this page helpful?