Skip to main content
Every request to the CUFinder API returns a standard HTTP status code together with a JSON body that includes a status field. Check both to confirm whether a request succeeded and to handle failures programmatically.

​
Response shape

Successful and failed requests share a consistent envelope, so you can branch on status before reading data.
​
status
integer
1 when the request succeeds, -1 when it fails. Always check status in addition to the HTTP status code.
​
message
string
Present only on errors. A human-readable explanation of what went wrong.

​
Quick reference

​
200 — OK

The request was processed successfully.
The response data object contains your result, and credit_count reports your remaining balance. A 200 is only returned when status is 1.
Response

​
400 — Not enough credits

Your account does not have enough credits to complete the request. How to resolve
  • Review your remaining balance from the dashboard.
  • Top up credits or upgrade your plan, then retry the request.
Response

​
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

​
422 — Unprocessable Entity

The request reached the API but could not be processed — usually a missing required field, a typo in a parameter name, or a value in the wrong format. How to resolve
  • Check the Attributes section of the endpoint for required parameters and accepted formats.
  • Send the body as application/x-www-form-urlencoded (or JSON) with the exact field names shown in the request sample.
Response

​
500 — Server Error

Something went wrong on our side. These are rare. How to resolve
  • Retry the request after a short delay.
  • If the error persists, contact support with the request details so we can investigate.
Response
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.