Platinux API

Errors

Every error code, what it means and what to do.

View as Markdown

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.

json
{ "error": "insufficient_credits", "message": "this score costs 10 credits" }

Invalid domains also carry a one-word reason (see Domain checks):

json
{ "error": "invalid_domain", "reason": "file_name" }

Switch on error (and reason), not on message. Messages are for people and may change.

All error codes

HTTPerrorEndpointsWhat to do
400invalid_inputAllFix the field named in message (or send valid JSON)
400invalid_domainScoring, companySend the company's own website. reason says what was wrong
400invalid_email/score/email, email → domainSend a valid email address
400invalid_url/score/socialSend a LinkedIn company or person URL (reason: not_linkedin)
400too_many_inputs/score/…/bulkSend at most 1,000 inputs per call
400too_many_domainsBulkSend at most 1,000 domains per call
400too_many_emailsEmail bulkSend at most 1,000 emails per call
401unauthorizedAllSend a valid key: Authorization: Bearer plx_live_…
402insufficient_creditsScoring, company, email → domainTop up credits in the app
403template_not_allowedScoringUse one of your own templates
404job_not_foundScoreCheck job_id. Jobs are visible only to the account that started them
404batch_not_foundBulkCheck batch_id
404not_found/score/…Unknown path: use /score/domain, /score/email or /score/social
405method_not_allowedAllUse the method shown in the reference
409template_not_liveScoringUse the template with is_live: true
409batch_in_progressBulk scoringWait for your running batch to finish
422template_emptyScoringSwitch on at least one signal in your live template
500internal_errorAllSomething failed on our side. Try again
502provider_unavailableCompany, email → domainA 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: 402 after topping up; 409 batch_in_progress after the running batch completes.
  • Scoring is safe to repeat: sending the same domain again returns the running or recent job instead of charging twice.