Errors - Up2Data

Error envelope

All errors share one shape:

{
  "error": {
    "type": "unprocessable_target",
    "message": "This profile is private or has been deleted.",
    "requestId": "req_9k2mm4xd"
  }
}

requestId appears on every response, success or failure — include it in support requests.

Error types

Status	`error.type`	Meaning	Billed?
`400`	`invalid_request`	Malformed body, unknown field, bad URL format.	No
`401`	`invalid_api_key`	Missing, malformed, or revoked key.	No
`402`	`insufficient_credits`	Balance can’t cover the operation.	No
`404`	`not_found`	Resource (Signal, Trigger, job) doesn’t exist.	No
`422`	`unprocessable_target`	Target profile/company is private, deleted, or unreachable.	No
`429`	`rate_limited`	Over your request or concurrent-batch limit. Honor `Retry-After`.	No
`500`	`internal_error`	Something broke on our side.	No
`504`	`upstream_timeout`	Live scrape didn’t complete in time.	No

The billing column is the contract: if you didn’t get data, you didn’t pay. The complete matrix — including partial batch results and Signal checks — is in Pay-on-success.

Batch semantics

Batch jobs succeed and fail per item. A 1,000-item job where 970 entities resolve bills those 970 (each at its entity’s cost); the 30 failures are listed in the job result with per-item error types and cost nothing.

Retries

429, 500, 504 are safe to retry — failed attempts were not billed.
Use exponential backoff with jitter; treat Retry-After as the floor when present.
Batch submissions accept an Idempotency-Key header so a retried submission can’t create a duplicate job.