Errors and recovery - Pascal Developer Docs

Expected request errors use this envelope. Unexpected server errors return a plain 500 without it:

{"error": {"code": "invalid_request", "message": "Validation error", "details": null}}

code and message are strings. details is an object, array, or null. All 401 responses carry WWW-Authenticate: Bearer.

HTTP	Code	When
400	`invalid_request`	Malformed body/form or request validation failure
400	`invalid_record`	Invalid batch; `details.records` lists `{index, id, reason}`; nothing staged
401	`invalid_client`	Token exchange authentication failed, including disabled connector
401	`invalid_token`	Data route bearer token is missing, invalid, expired, or issued before a key rotation
403	`connector_disabled`	Connector disabled on a data route
403	`datasource_mismatch`	Requested datasource differs from the token datasource
404	`upload_not_found`	Unknown upload id
404	`not_found`	Unknown path
405	`method_not_allowed`	HTTP method is not supported on this path
409	`upload_not_open`	PUT targets a status other than `in_progress` or an upload with `closed_at` set, or a sweep races close; details carry `status` and `closed`
409	`upload_processing`	Another upload is processing; honor `Retry-After`
410	`upload_expired`	Upload expired, including an upload replaced by a newer open
413	`batch_too_large`	Batch exceeds limits; details include `records`, `bytes`, `max_records`, `max_bytes`
413	`payload_too_large`	Body rejected before parsing; `details.max_bytes` gives the limit
422 (asynchronous)	`too_many_deletions`	Full upload deletion brake; appears in the upload’s `error` field, while close itself still returns 202
422 (asynchronous)	`validation_failed`	Records failed schema validation; appears in the upload’s `error` field with the report in `report`, while close itself still returns 202
429	`rate_limited`	Token exchange rate exceeded
503	`not_configured`	Custom Source connector configuration is unavailable
503	`publish_failed`	Close could not schedule the processing job; close again after `Retry-After`
503	`service_unavailable`	Any route; transient service failure; `details.retryable` is a boolean

The service_unavailable error includes a retry hint in the envelope:

{"error": {"code": "service_unavailable", "message": "Transient service failure", "details": {"retryable": true}}}

details.retryable is a boolean; inspect it before deciding whether to retry. A successful close means processing was submitted, not that records were accepted. On 503 publish_failed, the upload stays in_progress; honor Retry-After: 5 and call close again to retry scheduling. Poll until the upload leaves in_progress. A worker failure keeps it in_progress while Pascal retries; after at least one hour, the hourly stuck-upload sweep marks it failed with processing_timeout. A rejected or failed upload carries its error envelope in the upload’s error field; access the code as upload["error"]["error"]["code"]. processing_timeout appears only there. Correct invalid records before resending the whole rejected batch. A PUT timeout can be retried with the same ids. On a data-route 401, re-exchange a token and resume the same upload. On 409 upload_processing, wait for Retry-After before trying to open again. For expired, rejected, or failed uploads, open a new upload and resend the intended records.