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 unavailable — a backend service is temporarily down.

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.
Name
BRAND_NOT_FOUND
Description
No brand exists with the given ID or URL.
Name
SERVICE_UNAVAILABLE
Description
A backend service (e.g., search engine) is temporarily unavailable.
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
    }
  }
}