Skip to main content
Every request to the CUFinder API returns a standard HTTP status code together with a JSON envelope. Successful lookups are 200 with "success": true. Most failures use meaningful 4xx/5xx codes with "success": false and a stable, machine-readable error.code, with one exception: a not-found lookup also returns HTTP 200, with "success": false and error.code of not_found. Always branch on the success flag (or error.code), not on the HTTP status alone.

​
Response shape

​
object
The endpoint’s result. List endpoints return plural arrays (companies, people, jobs, …) and include meta.pagination with { "page", "has_more" }.
​
object
charged is what this call cost; remaining is your balance after it. Credits are only charged when success is true, errors, including not-found lookups, never charge, and an insufficient-credits check runs before any work starts.
​
string
Present only on errors. A stable identifier you can branch on: invalid_request, unauthorized, insufficient_credits, not_found, request_timeout, validation_failed, rate_limited, internal_error.

​
Quick reference

​
200: OK

The request was processed successfully.
data contains your result and meta.credits reports the cost and your remaining balance. Note that an empty search result is still a 200, list endpoints return an empty array rather than an error, and the request is charged normally.

​
400: Invalid request

The request body could not be processed at all, most commonly invalid JSON or a wrong content type. How to resolve
  • Send a JSON body with Content-Type: application/json.
  • Validate your JSON before sending.

​
401: Unauthorized

The x-api-key header is missing, malformed, or invalid. How to resolve
  • Confirm you are sending the x-api-key header on every request.
  • Copy your key exactly from Account » API key in the dashboard, keys are case-sensitive and contain no spaces.
  • Make sure the key has not been rotated or revoked.
Response

​
402: Insufficient credits

Your account does not have enough credits for this request. The check runs before any work is performed, so nothing is charged and no lookup happens. How to resolve
  • Review your remaining balance from the dashboard or from meta.credits.remaining on any successful call.
  • Top up credits or upgrade your plan, then retry the request.
Response

​
Not found (200 with success: false)

The specific entity you addressed, a company, a person, a domain, could not be resolved. The HTTP status is 200, so check the success flag or error.code to detect it. You were not charged. How to resolve
  • Double-check the identifier: domains without typos, full LinkedIn URLs, exact spellings.
  • Try an alternative identifier, for example a domain instead of a company name.
  • Remember: search endpoints never return not_found for “no matches”; they return "success": true with an empty array.
Response

​
408: Request timeout

The upstream data source took too long to answer. You were not charged. How to resolve
  • Retry the request, timeouts are usually transient.
  • If one endpoint times out repeatedly for the same input, try again later or contact support.
Response

​
422: Validation failed

The request reached the API but a required field is missing or a value is invalid. The details array names each problem field. How to resolve
  • Read error.details, each entry has the field and the issue.
  • Check the endpoint’s Attributes section for required parameters and accepted values.
Response

​
429: Rate limited

You are sending requests faster than your key allows. How to resolve
  • Slow your request rate and retry after a short delay.
  • Spread batch jobs over time instead of bursting.

​
500: Server error

Something went wrong on our side. These are rare, and you are never charged for them. How to resolve
  • Retry the request after a short delay.
  • If the error persists, contact support with the request details so we can investigate.
Before contacting support, double-check your request against the endpoint’s Attributes and the codes above, most errors are resolved by correcting the API key, credits, or parameters.