Errors
Every error code, what it means and what to do.
Errors use normal HTTP status codes and always have the same JSON shape: an error code you can switch on, and usually a short message.
{ "error": "insufficient_credits", "message": "this score costs 10 credits" }Invalid domains also carry a one-word reason (see Domain checks):
{ "error": "invalid_domain", "reason": "file_name" }Switch on error (and reason), not on message. Messages are for people and may change.
All error codes
| HTTP | error | Endpoints | What to do |
|---|---|---|---|
| 400 | invalid_input | All | Fix the field named in message (or send valid JSON) |
| 400 | invalid_domain | Scoring, company | Send the company's own website. reason says what was wrong |
| 400 | invalid_email | /score/email, email → domain | Send a valid email address |
| 400 | invalid_url | /score/social | Send a LinkedIn company or person URL (reason: not_linkedin) |
| 400 | too_many_inputs | /score/…/bulk | Send at most 1,000 inputs per call |
| 400 | too_many_domains | Bulk | Send at most 1,000 domains per call |
| 400 | too_many_emails | Email bulk | Send at most 1,000 emails per call |
| 401 | unauthorized | All | Send a valid key: Authorization: Bearer plx_live_… |
| 402 | insufficient_credits | Scoring, company, email → domain | Top up credits in the app |
| 403 | template_not_allowed | Scoring | Use one of your own templates |
| 404 | job_not_found | Score | Check job_id. Jobs are visible only to the account that started them |
| 404 | batch_not_found | Bulk | Check batch_id |
| 404 | not_found | /score/… | Unknown path: use /score/domain, /score/email or /score/social |
| 405 | method_not_allowed | All | Use the method shown in the reference |
| 409 | template_not_live | Scoring | Use the template with is_live: true |
| 409 | batch_in_progress | Bulk scoring | Wait for your running batch to finish |
| 422 | template_empty | Scoring | Switch on at least one signal in your live template |
| 500 | internal_error | All | Something failed on our side. Try again |
| 502 | provider_unavailable | Company, email → domain | A data source didn't answer. Try again; nothing was charged |
Retrying
- Safe to retry:
500,502, and network errors. Wait a few seconds, then back off. - Don't retry unchanged:
400,401,403,404,422. The same request will fail the same way. - Retry later:
402after topping up;409 batch_in_progressafter the running batch completes. - Scoring is safe to repeat: sending the same domain again returns the running or recent job instead of charging twice.