Errors

API error codes provide information about the status of your request. If a request cannot be completed, the API will return an error code that helps identify the cause of the issue and the steps needed to resolve it.

400 Bad Request

The request is invalid, often due to missing required parameters, incorrect formatting, or invalid input data. Check the request parameters and ensure all required fields are included with the correct format.

Common cases:

• Company/supplier search with no name, phone, or website
• page_size that is not a positive number
• Dates that are not mm/dd/yyyy
• More than one * or more than three ? wildcards in a field
• fields and exclude sent together, an empty list of field names, or a format other than json or toon — see Response shaping

{
  "statusCode": 400,
  "message": "page_size must be a positive number",
  "error": "Bad Request"
}

{
  "statusCode": 400,
  "message": ["Start date must be in the format mm/dd/yyyy"],
  "error": "Bad Request"
}

{
  "statusCode": 400,
  "message": [
    "product_description must contain no more than 1 (*) wildcard and no more than 3 (?) wildcards"
  ],
  "error": "Bad Request"
}

401 Unauthorized

No valid API key was provided, or the API key is missing or invalid. Verify that the API key is included in the request and that it is correct. See Authentication.

{
  "message": "Unauthorized",
  "statusCode": 401
}

403 Forbidden

The API key is valid, but the request cannot be completed because there are not enough data credits. Check the account subscription, payment status, or available credits. See Credits.

{
  "statusCode": 403,
  "message": "Not enough credits",
  "error": "Forbidden"
}

A 403 that asks you to contact support is an account-level block rather than anything wrong with your request. Send us the request path and the time and we will clear it.

One of those is specific to search. Search endpoints are generally not charged separately, but an integration that uses search as the primary way of retrieving data — without subsequently calling the corresponding data endpoint — can stop working:

{
  "statusCode": 403,
  "message": "Search limit reached. Please contact support.",
  "error": "Forbidden"
}

If your search requests stop working, just reach out to us. We’ll make the necessary switch on our end so you can continue using the search endpoint as intended. See Search Credits.

404 Not Found

The requested resource or endpoint does not exist. Verify the URL, endpoint path, and resource ID. These routes are GET-only; using POST, PUT, PATCH, or DELETE also returns 404.

{
  "message": "Company Not Found",
  "error": "Not Found",
  "statusCode": 404
}

Other 404 messages you may see:

• Supplier Not Found
• Not Found (BOL or product)
• Cannot POST /v1.0/company/search (wrong HTTP method)

301 Moved Permanently (slug redirect)

Some company/supplier slugs permanently redirect to a canonical path:

{
  "statusCode": 301,
  "message": "This resource has been permanently moved",
  "redirectTo": "https://data.importyeti.com/v1.0/company/new-slug"
}

Follow redirectTo (and the Location header when present).

429 Too Many Requests

The API does not publish a fixed request-rate limit, and a normal integration will not see a 429. It is not unlimited either — sustained heavy use can get an account throttled. When a 429 does arrive, the message tells you which of two things happened.

Your account is being throttled. Pace your requests and retry with backoff. Contact support if you do not know why it started.

{
  "statusCode": 429,
  "message": "This endpoint is temporarily throttled. Please slow down a bit."
}

A service the endpoint depends on is rate limiting. Here the message names the operation that failed instead of talking about your request rate. Your key and your usage are fine, and slowing down will not clear it. Retry, and contact support if it persists.

{
  "statusCode": 429,
  "message": "Failed to get database update date: Too Many Requests"
}

500 Internal Server Error

An unexpected error occurred on the API server side. Retry the request later. If the issue continues, contact support with the request path and time.