Error Registry Complete list of error codes returned by the Parseo API.
All error responses use application/problem+json and follow this shape:
{ "type" : "https://docs.parseo.app/errors/error-registry" , "title" : "Invoice not found" , "status" : 404 , "detail" : "The specified invoice was not found" , "instance" : "/v1/invoices/inv_01HXYZ..." , "requestId" : "req_01HXYZ..." , "code" : "invoice.not_found" } The code field is the stable, machine-readable identifier — always branch on code, not on title or detail.
Code Status Description Remediation auth.missing_credentials401 No API key was provided. Send Authorization: Bearer <key> on every request. auth.invalid_key401 The API key does not exist or is malformed. Verify the key value and that it has not been deleted. auth.key_revoked401 The API key was explicitly revoked. Rotate to a new key from the dashboard. auth.key_expired401 The API key has passed its expiration date. Issue a new key or extend the expiration in the dashboard. auth.too_many_failed_attempts429 Too many failed authentication attempts from this source. Honor the Retry-After header and stop retrying with the invalid credential.
Code Status Description Remediation auth.insufficient_scope403 The API key lacks the scope required for this endpoint. Grant the missing scope in the dashboard or use a key that already has it. auth.ip_not_allowed403 The request originated from an IP not in the key's allowlist. Add the caller's IP to the key's allowlist or call from an allowed network. plan.api_access_disabled403 Your team's plan does not include API access. Upgrade the team plan to one that includes public API access. client.not_found404 The X-Client-Id header references a client that does not exist. Verify the client ID and that it has not been deleted. client.not_in_team403 The referenced client does not belong to your team. Use a client ID owned by the authenticated team. client.scope_mismatch403 This key is scoped to a specific client and X-Client-Id must match it. Send the scoped client's ID, or use a team-scoped key.
Code Status Description Remediation rate_limit.exceeded429 The per-key rate limit was exceeded. Back off until the Retry-After seconds elapse, then retry.
Code Status Description Remediation ingestion.queue_full503 The ingestion queue is at capacity. Retry after a short delay with jittered backoff.
Code Status Description Remediation invoice.not_found404 No invoice matches the supplied ID for this team. Verify the invoice ID and that the authenticated team owns it. job.not_found404 No processing job matches the supplied ID for this team. Verify the job_... ID returned by POST /invoices. Jobs are retained for 30 days after terminal state. contact.not_found404 No contact matches the supplied ID for this team. Verify the contact ID and that the authenticated team owns it. auth.key_suspended403 Ops has administratively suspended this API key. Contact support — partners cannot self-restore a suspended key. invoice.reprocess_unavailable409 The original source file is no longer retained for this invoice, so it cannot be reprocessed. Re-upload the source file to create a new invoice. invoice.not_ready_for_export409 The invoice is still queued or processing. Poll the invoice until status is completed, then retry the export. invoice.export_unavailable_failed409 Processing failed, so the invoice cannot be exported. Re-upload the source file or fix the parsing issue before exporting. invoice.not_editable409 Invoice is still being processed and cannot be edited yet. Poll GET /invoices/{id}/status until the invoice reaches a terminal state (processed or failed), then retry the update.
Code Status Description Remediation export.invalid_format400 The requested export format is not supported. Use one of: rivile, finvalda, centas, agnum, json, xml.
Code Status Description Remediation upload.no_file400 The multipart body did not include a file part. Send the document as a multipart/form-data field named file. upload.invalid_mime_type400 The uploaded file's MIME type is not supported. Upload a application/pdf, image/jpeg, image/png, or image/webp file. upload.file_too_large413 The uploaded file exceeds the 50 MB per-file limit. Compress or split the document and retry. upload.filename_too_long400 The filename is longer than 255 bytes. Rename the file to 255 bytes or fewer and retry. upload.payload_too_large413 The total request body exceeds the configured maximum (50 MB single / 500 MB batch). Reduce the payload size or split a batch into smaller requests. upload.concurrent_limit_exceeded429 Too many concurrent uploads from this team. Reduce parallelism or honor the Retry-After header. invoice.upload_failed500 The upload was accepted but a downstream step (storage, queue) failed before the job could be enqueued. Retry with the same Idempotency-Key.
Code Status Description Remediation idempotency.request_in_progress409 A prior request using this Idempotency-Key is still being processed. Wait briefly and retry with the same key; the cached response will be returned once the original completes. idempotency.key_reused_with_different_params409 The Idempotency-Key was previously used with a different request body. Generate a new idempotency key for the new request, or resend the original body verbatim. idempotency.backend_unavailable503 The idempotency cache is temporarily unreachable; the request was rejected fail-closed to avoid double-execution. Honour the Retry-After header and retry with the same key — the original request was not executed.
Code Status Description Remediation validation.invalid_body400 One or more request body fields failed validation. Per-field details are returned in the errors[] array. Inspect errors[].field and errors[].code to see which fields failed and correct them. validation.failed400/422 Generic validation failure when no per-field detail is available. Inspect detail for the human-readable explanation and correct the request. validation.invalid_idempotency_key400 The Idempotency-Key header is empty, exceeds 255 bytes, or contains control characters. Use a non-empty UTF-8 string of 1–255 printable characters (a UUID is fine). validation.client_mode_mismatch400 The referenced client's mode (live/test) does not match the authenticating key's mode. Use a client that matches the key's mode, or authenticate with a key whose mode matches the client. Live and test resources cannot cross-reference.
These appear inside the errors[].code array on validation.invalid_body responses (one entry per failing field).
Code Description validation.invalid_valueGeneric value-shape failure (default fallback). validation.invalid_formatValue did not match a required format (UUID, email, URL, ISO 8601, etc.). validation.requiredA required field was missing or empty. validation.lengthString/array length was outside the allowed bounds. validation.invalid_enumValue was not one of the allowed enum members. validation.invalid_typeValue was the wrong type (e.g. string where number expected). validation.invalid_public_idA public ID had the wrong prefix or was structurally invalid. validation.client_required_in_test_modeA test-mode upload was submitted without a client association. Set the X-Client-Id header or use a client-scoped API key. webhook.secret_rotation_grace_activeA second webhook-secret rotation was attempted while the previous one is still inside its 24h grace window. Wait until the grace period ends.
Code Status Description Remediation pagination.filter_mismatch400 The cursor was issued for a different filter set than the current request. Start a new pagination from page 1 without the cursor; keep filters consistent thereafter. pagination.cursor_invalid400 The cursor is malformed or produced by an incompatible API version. Start a new pagination without the cursor.
Code Status Description Remediation webhook.not_found404 No webhook endpoint matches the supplied ID for this team. Verify the endpoint ID and that it has not been deleted. webhook.endpoint_limit_exceeded422 The team has reached the maximum of 20 webhook endpoints. Delete an unused endpoint before creating a new one. webhook.url_not_https400 The webhook URL must use the https:// scheme. Use an HTTPS URL. webhook.url_invalid_hostname400 The hostname is not a valid public DNS name. Use a publicly resolvable hostname (no localhost, IPs, or .internal domains). webhook.url_resolves_to_private_ip400 The hostname resolves to a private or reserved IP range. Host the endpoint on a publicly routable address. webhook.url_port_not_allowed400 The URL specifies a disallowed port. Only port 443 is permitted. Remove the explicit port or use :443. webhook.url_too_long400 The URL exceeds 2048 characters. Shorten the URL. webhook.test_rate_limit_exceeded429 The per-endpoint test-delivery rate limit (10/hour) was exceeded. Wait for the hour window to roll over before sending more test deliveries. webhook.delivery_not_found404 No delivery attempt matches the supplied ID for this endpoint. Verify the delivery ID returned by GET /webhooks/{id}/deliveries. webhook.delivery_payload_unavailable409 The original payload is no longer retained for this delivery (past the 30-day retention window). Retrigger the event upstream instead of retrying this specific delivery.
Code Status Description Remediation service.maintenance503 The public API is temporarily unavailable for maintenance. Honor the Retry-After header and retry after the indicated interval. internal.server_error500 An unexpected server error occurred. Retry the request; if it persists, include the requestId when contacting support.
These codes are emitted when an underlying exception didn't carry its own
machine-readable identifier (rare — most public-API errors map to a
specific code above). Branch on these only as a last-resort default.
Code Status Description http.unauthorized401 Generic 401 fallback. http.forbidden403 Generic 403 fallback. http.not_found404 Generic 404 fallback (e.g. an unknown route). http.conflict409 Generic 409 fallback.
