Errors and Status Codes

The API uses a few predictable response patterns across all categories.

#Common Status Codes

• 200 OK: successful response, and sometimes provider-specific empty or not-found messages
• 400 Bad Request: malformed provider URL, unsupported remote response, or parser failure
• 401 Unauthorized: missing or invalid bearer token, or invalid secret_key
• 403 Forbidden: insufficient credits or blocked generic domain
• 422 Unprocessable Entity: request validation failed
• 429 Too Many Attempts: throttled endpoint, currently used on X search

#Common Error Payloads

Insufficient credits:

{
  "message": "You do not have enough credits to perform this action."
}

Invalid secret key:

{
  "message": "Invalid secret key"
}

Blocked generic-domain scrape:

{
  "message": "Domain not supported."
}

#Important Behavior

Credits are only deducted for successful requests.

Some provider-specific lookups intentionally return 200 plus a message instead of 404, for example:

• missing X/Twitter post
• missing X/Twitter user
• empty Upwork results
• private Upwork job

Design your client to inspect both status code and payload message.