Errors - Pulse API

Every failed request answers one problem (RFC 9457), and so does a failed job’s error. Branch on code, or on the HTTP status for a code you don’t know; retryable says whether sending the same request again may succeed. A code’s prefix (FILE_, PAYMENT_) is not a category: compare the whole code.

{
  "type": "https://docs.runpulse.com/errors/credentials-invalid",
  "title": "No valid credentials",
  "status": 401,
  "instance": "urn:pulse:request:req-6f1c2a9e-3b7d-4c55-9a8e-2d4f0b1c7e93",
  "code": "CREDENTIALS_INVALID",
  "request_id": "req-6f1c2a9e-3b7d-4c55-9a8e-2d4f0b1c7e93",
  "retryable": false
}

Members

Member	Meaning
`type`	This code’s page: what it means and what to do.
`title`	A short summary of the code, the same for every occurrence.
`status`	The HTTP status the code answers with.
`detail`	What happened this time.
`instance`	This occurrence: the request’s URN, `urn:pulse:request:<id>`.
`code`	The stable error code, e.g. `REQUEST_INVALID`. Branch on it.
`request_id`	The request that failed, as `X-Request-Id` named it; for a failed job, the request that created it. Quote it to support.
`retryable`	Whether the same request may succeed if sent again.
`errors`	Each refused part of the request.
`retry_after`	Seconds to wait before retrying, as `Retry-After` says. Only where a code adds it.
`resource`	What wasn’t found: `job`, `batch`, `webhook`, `config`, … Only where a code adds it.
`reason`	The cause within the code. Only where a code adds it.
`parse_id`	The parse the request recorded. Only where a code adds it.
`extract_id`	The extraction it recorded. Only where a code adds it.
`split_id`	The split it recorded. Only where a code adds it.
`classify_id`	The classification it recorded. Only where a code adds it.
`tables_id`	The tables job it recorded. Only where a code adds it.
`charts_id`	The charts job it recorded. Only where a code adds it.
`pipeline_id`	The pipeline it recorded. Only where a code adds it.
`batch_id`	The batch it recorded. Only where a code adds it.
`filename`	The file refused. Only where a code adds it.
`declared_type`	The type its name declared. Only where a code adds it.
`detected`	The type its contents are. Only where a code adds it.
`supported_types`	The types accepted. Only where a code adds it.
`supported`	The values accepted. Only where a code adds it.
`max_size_mb`	The largest size accepted. Only where a code adds it.
`file_size_mb`	The file’s size. Only where a code adds it.
`plan_name`	Your organization’s plan. Only where a code adds it.
`pages_used`	Pages used this period. Only where a code adds it.
`page_allowance`	Pages the plan allows. Only where a code adds it.
`upgrade_url`	Where to change your plan. Only where a code adds it.
`action_required`	What to do to continue. Only where a code adds it.
`billing_info`	Your organization’s billing state, as the gate read it. Only where a code adds it.

Formats

An error answers application/problem+json, or application/json when Accept names it and not problem+json at the same or a higher q-value; text/markdown listed first gets the same problem as Markdown. Every response carries X-Request-Id, the problem’s request_id: quote it to support.

Codes

Code	Status	Title	Retryable
`CREDENTIALS_INVALID`	`401`	No valid credentials	No
`API_KEY_INACTIVE`	`401`	API key is inactive	No
`PERMISSION_DENIED`	`403`	Permission denied	No
`REQUEST_INVALID`	`400`	Invalid request	No
`UNSUPPORTED_VERSION`	`400`	Unsupported API version	No
`PAGE_RANGE_INVALID`	`400`	Invalid page range	No
`RESOURCE_UNUSABLE`	`400`	Resource can’t be used	No
`FIELD_TOO_LARGE`	`413`	Form field too large	No
`FILE_TYPE_UNSUPPORTED`	`415`	Unsupported file type	No
`FILE_TOO_LARGE`	`413`	File too large	No
`FILE_CORRUPT`	`422`	File corrupted	No
`DOCUMENT_UNPROCESSABLE`	`422`	Document can’t be processed	No
`FILE_EMPTY`	`422`	Empty file	No
`FILE_DOWNLOAD_FAILED`	`422`	File couldn’t be downloaded	No
`FILE_DOWNLOAD_TIMEOUT`	`504`	File download timed out	Yes
`FILE_URL_INVALID`	`400`	Invalid file URL	No
`FILE_UNSAFE`	`422`	Unsafe PDF content	No
`TRIAL_EXPIRED`	`402`	Trial expired	No
`CREDIT_LIMIT_EXCEEDED`	`402`	Credit limit exceeded	No
`PAYMENT_REQUIRED`	`402`	Payment required	No
`PLAN_LIMIT_REACHED`	`402`	Plan limit reached	No
`PLAN_UPGRADE_REQUIRED`	`402`	Plan upgrade required	No
`ACCOUNT_SUSPENDED`	`403`	Account suspended	No
`PAYMENT_FAILED`	`402`	Payment failed	No
`PAYMENT_AUTHENTICATION_REQUIRED`	`402`	Payment requires authentication	No
`SUBSCRIPTION_CANCELED`	`402`	Subscription canceled	No
`SUBSCRIPTION_PAST_DUE`	`402`	Subscription past due	No
`PROCESSING_FAILED`	`500`	Document processing failed	Yes
`PROCESSING_TIMEOUT`	`504`	Processing timed out	Yes
`RESOURCE_NOT_FOUND`	`404`	Not found	No
`ROUTE_NOT_FOUND`	`404`	Route not found	No
`JOB_ALREADY_ENDED`	`409`	Job already ended	No
`JOB_NOT_FINISHED`	`409`	Job still processing	Yes
`RESULT_ALREADY_FETCHED`	`410`	Result already fetched	No
`RESULT_EXPIRED`	`410`	Result no longer available	No
`JOB_CANCELED`	`410`	Job canceled	No
`WEBHOOK_LIMIT_REACHED`	`422`	Webhook limit reached	No
`RATE_LIMIT_EXCEEDED`	`429`	Rate limit exceeded	Yes
`CAPACITY_EXCEEDED`	`503`	Pulse is at capacity	Yes
`SERVICE_UNAVAILABLE`	`503`	Service unavailable	Yes
`SERVER_ERROR`	`500`	Internal server error	Yes
`JOB_UNREADABLE`	`500`	Job can’t be read	No
`METHOD_NOT_ALLOWED`	`405`	Method not allowed	No
`LICENSE_INVALID`	`503`	License invalid or expired	No
`LICENSE_NOT_ACTIVATED`	`503`	Deployment not activated	No

From API version 1

Version 1	Version 2
`AUTH_001`	`CREDENTIALS_INVALID`
`AUTH_002`	`CREDENTIALS_INVALID`
`AUTH_003`	`CREDENTIALS_INVALID`
`AUTH_004`	`PERMISSION_DENIED`
`AUTH_005`	`CREDENTIALS_INVALID`
`AUTH_008`	`API_KEY_INACTIVE`
`BILLING_001`	`TRIAL_EXPIRED`
`BILLING_002`	`CREDIT_LIMIT_EXCEEDED`
`BILLING_003`	`PAYMENT_REQUIRED`
`BILLING_004`	`PLAN_LIMIT_REACHED`
`BILLING_006`	`ACCOUNT_SUSPENDED`
`BILLING_007`	`PAYMENT_FAILED`
`BILLING_008`	`PAYMENT_AUTHENTICATION_REQUIRED`
`BILLING_009`	`SUBSCRIPTION_CANCELED`
`BILLING_010`	`SUBSCRIPTION_PAST_DUE`
`BILLING_012`	`PLAN_LIMIT_REACHED`
`BILLING_013`	`PLAN_UPGRADE_REQUIRED`
`EXPIRED`	`RESULT_EXPIRED`
`FILE_001`	`FILE_TYPE_UNSUPPORTED`
`FILE_002`	`FILE_TOO_LARGE`
`FILE_003`	`FILE_CORRUPT`
`FILE_004`	`FILE_EMPTY`
`FILE_005`	`FILE_DOWNLOAD_FAILED`
`FILE_006`	`FILE_DOWNLOAD_TIMEOUT`
`FILE_007`	`FILE_URL_INVALID`
`FILE_008`	`FILE_UNSAFE`
`GENERAL_001`	`SERVER_ERROR`
`GENERAL_002`	`SERVICE_UNAVAILABLE`
`GENERAL_003`	`PROCESSING_TIMEOUT`
`GENERAL_004`	`RATE_LIMIT_EXCEEDED`
`GENERAL_007`	`METHOD_NOT_ALLOWED`
`GONE`	`RESULT_EXPIRED`
`INVALID_REQUEST`	`REQUEST_INVALID`
`JOB_001`	`RESOURCE_NOT_FOUND`
`JOB_002`	`JOB_ALREADY_ENDED`
`JOB_003`	`RESULT_EXPIRED`
`JOB_004`	`JOB_NOT_FINISHED`
`JOB_005`	`PROCESSING_FAILED`
`LICENSE_001`	`LICENSE_INVALID`
`LICENSE_002`	`LICENSE_NOT_ACTIVATED`
`NOT_FOUND`	`RESOURCE_NOT_FOUND`
`PROC_001`	`PROCESSING_FAILED`
`PROC_002`	`PROCESSING_TIMEOUT`
`PROC_003`	`SERVICE_UNAVAILABLE`
`PROC_004`	`CAPACITY_EXCEEDED`
`PROC_005`	`PROCESSING_FAILED`
`RATE_001`	`RATE_LIMIT_EXCEEDED`
`REQ_001`	`REQUEST_INVALID`
`REQ_002`	`REQUEST_INVALID`
`REQ_003`	`REQUEST_INVALID`
`REQ_004`	`REQUEST_INVALID`
`REQ_005`	`REQUEST_INVALID`
`REQ_006`	`PAGE_RANGE_INVALID`
`REQ_007`	`FIELD_TOO_LARGE`
`SCHEMA_001`	`REQUEST_INVALID`
`STORAGE_001`	`SERVER_ERROR`
`STORAGE_002`	`RESOURCE_NOT_FOUND`
`STORAGE_003`	`SERVICE_UNAVAILABLE`
`STORAGE_005`	`RESULT_EXPIRED`
`WEBHOOK_001`	`WEBHOOK_LIMIT_REACHED`
`AUTH_006`	No version 2 code
`AUTH_007`	No version 2 code
`BATCH_001`	No version 2 code
`BILLING_005`	No version 2 code
`BILLING_011`	No version 2 code
`GENERAL_005`	No version 2 code
`PIPELINE_001`	No version 2 code
`PIPELINE_002`	No version 2 code
`PIPELINE_003`	No version 2 code
`PIPELINE_004`	No version 2 code
`PIPELINE_005`	No version 2 code
`PIPELINE_006`	No version 2 code
`PIPELINE_007`	No version 2 code
`SCHEMA_002`	No version 2 code
`SCHEMA_003`	No version 2 code
`SCHEMA_004`	No version 2 code
`SCHEMA_005`	No version 2 code
`STORAGE_004`	No version 2 code