API error contract

Generated from API_ERROR_CATALOG. Regenerate this page from that catalog. Do not type the code list by hand.

Every error response is { success: false, error }. error always includes code, message, remediation, and requestId. fields is present when the failure names individual inputs. details carries any extra structured context.

A handler may emit a stable code that is not in this list yet. That response still has the four required fields and uses the generic remediation until the code is added to the catalog.

Codes

AUTH_EXPIRED: The API key has expired Create a new API key and retry.
AUTH_INSUFFICIENT_SCOPE: The API key does not have the required scope Use a key whose scopes include the required action.
AUTH_INVALID_KEY: The provided API key is invalid Create a new API key and send it in the Authorization header.
AUTH_MISSING: User authentication is required Sign in and retry the request.
AUTH_MISSING_KEY: API key is required for this request Send an API key in the Authorization header.
BODY_TOO_LARGE: Request body is too large Reduce the payload below the stated limit and send it again.
CAPABILITY_MISSING: A required database capability is missing Enable the extension in Settings → Database, or switch providers.
CONFLICT: The resource is in a conflicting state Reload the resource and retry the action that matches its current state.
CSRF_REJECTED: Cross-origin request rejected Send the request from an allowed origin with the CSRF token.
DATABASE_ERROR: A database operation failed Retry later. Include the request id if the failure continues.
DB_NOT_CONFIGURED: No database is configured Configure the database in Settings, or set CONTROL_PLANE_DATABASE_URL.
EXTRACTION_FAILED: Data extraction failed for this page Check the page and the extractor, then retry.
EXTRACTION_INVALID_SELECTOR: The extraction selector is invalid Correct the selector and retry.
FORBIDDEN: You do not have permission for this action Use an account or key that is allowed to perform the action.
INTERNAL_ERROR: An unexpected internal error occurred Retry later and include the request id if you contact support.
INVALID_BODY: The request body is invalid Send a JSON body that matches the documented fields.
JOB_CANCELLED: The job was cancelled Start a new job if you still need the result.
JOB_FAILED: The job failed during execution Read the job error and start a new job after fixing the cause.
JOB_NOT_FOUND: The specified job was not found Check the job id and that this workspace owns it.
JOB_TIMEOUT: The job exceeded the maximum execution time Retry the job, or raise the timeout if the page is slow.
LIST_CURSOR_INVALID: The list cursor is not valid Use the nextCursor from the previous page, or omit cursor to read the first page.
LIST_FILTER_INVALID: A list filter is not valid Send filter as field:operator:value. field:value means equality. Repeat filter to AND conditions.
LIST_LIMIT_INVALID: The list limit is not valid Send limit as a positive integer at or below the endpoint maximum.
MULTI_TENANT_UNSUPPORTED: This deployment does not serve multiple tenants Turn off the multi-tenant flag or use a deployment that supports it.
NETWORK_ERROR: A network request failed Check connectivity and retry.
NOT_FOUND: The resource was not found Check the id and that this key can see the resource.
PROXY_AUTH_FAILED: Proxy authentication failed Update the proxy credentials and retry.
PROXY_UNAVAILABLE: No available proxies in the assigned pool Choose another proxy pool or retry later.
RATE_LIMITED: Too many requests Wait for the limit to reset, then retry.
RATE_LIMIT_EXCEEDED: API rate limit exceeded, try again later Wait for the limit to reset, then retry.
REQUEST_SIGNATURE_INVALID: The request signature does not match. Recompute the HMAC over the canonical request with the current signing secret.
REQUEST_SIGNATURE_MISSING: This endpoint requires a signed request. Send x-pyrosync-timestamp, x-pyrosync-nonce, and x-pyrosync-signature. See the request signing guide.
REQUEST_SIGNATURE_REPLAY: This nonce was already used. Sign the request again with a new nonce.
REQUEST_SIGNATURE_STALE: The request timestamp is outside the allowed window. Sign a new timestamp within five minutes of the server clock.
TARGET_DISABLED: The target is currently disabled Enable the target, then retry.
TARGET_INVALID_URL: The target URL is not a valid URL Send an http or https URL and retry.
TARGET_NOT_FOUND: The specified scrape target was not found Check the target id and that this workspace owns it.
UNAUTHORIZED: The request is not authorized Send valid credentials or a valid signature and retry.
VALIDATION_ERROR: Request validation failed Fix the fields listed in the error and send the request again.
WEBHOOK_DELIVERY_FAILED: Failed to deliver webhook payload Check the endpoint and retry delivery.
WORKER_OVERLOADED: All workers are at maximum capacity Retry after the queue drains.
WORKER_UNAVAILABLE: No workers are currently available Retry after a worker becomes available.

API error contract

Generated from API_ERROR_CATALOG. Regenerate this page from that catalog. Do not type the code list by hand.

A handler may emit a stable code that is not in this list yet. That response still has the four required fields and uses the generic remediation until the code is added to the catalog.

Codes

AUTH_EXPIRED: The API key has expired Create a new API key and retry.

AUTH_INSUFFICIENT_SCOPE: The API key does not have the required scope Use a key whose scopes include the required action.

AUTH_INVALID_KEY: The provided API key is invalid Create a new API key and send it in the Authorization header.

AUTH_MISSING: User authentication is required Sign in and retry the request.

AUTH_MISSING_KEY: API key is required for this request Send an API key in the Authorization header.

BODY_TOO_LARGE: Request body is too large Reduce the payload below the stated limit and send it again.

CAPABILITY_MISSING: A required database capability is missing Enable the extension in Settings → Database, or switch providers.

CONFLICT: The resource is in a conflicting state Reload the resource and retry the action that matches its current state.

CSRF_REJECTED: Cross-origin request rejected Send the request from an allowed origin with the CSRF token.

DATABASE_ERROR: A database operation failed Retry later. Include the request id if the failure continues.

DB_NOT_CONFIGURED: No database is configured Configure the database in Settings, or set CONTROL_PLANE_DATABASE_URL.

EXTRACTION_FAILED: Data extraction failed for this page Check the page and the extractor, then retry.

EXTRACTION_INVALID_SELECTOR: The extraction selector is invalid Correct the selector and retry.

FORBIDDEN: You do not have permission for this action Use an account or key that is allowed to perform the action.

INTERNAL_ERROR: An unexpected internal error occurred Retry later and include the request id if you contact support.

INVALID_BODY: The request body is invalid Send a JSON body that matches the documented fields.

JOB_CANCELLED: The job was cancelled Start a new job if you still need the result.

JOB_FAILED: The job failed during execution Read the job error and start a new job after fixing the cause.

JOB_NOT_FOUND: The specified job was not found Check the job id and that this workspace owns it.

JOB_TIMEOUT: The job exceeded the maximum execution time Retry the job, or raise the timeout if the page is slow.

LIST_CURSOR_INVALID: The list cursor is not valid Use the nextCursor from the previous page, or omit cursor to read the first page.

LIST_FILTER_INVALID: A list filter is not valid Send filter as field:operator:value. field:value means equality. Repeat filter to AND conditions.

LIST_LIMIT_INVALID: The list limit is not valid Send limit as a positive integer at or below the endpoint maximum.

MULTI_TENANT_UNSUPPORTED: This deployment does not serve multiple tenants Turn off the multi-tenant flag or use a deployment that supports it.

NETWORK_ERROR: A network request failed Check connectivity and retry.

NOT_FOUND: The resource was not found Check the id and that this key can see the resource.

PROXY_AUTH_FAILED: Proxy authentication failed Update the proxy credentials and retry.

PROXY_UNAVAILABLE: No available proxies in the assigned pool Choose another proxy pool or retry later.

RATE_LIMITED: Too many requests Wait for the limit to reset, then retry.

RATE_LIMIT_EXCEEDED: API rate limit exceeded, try again later Wait for the limit to reset, then retry.

REQUEST_SIGNATURE_INVALID: The request signature does not match. Recompute the HMAC over the canonical request with the current signing secret.

REQUEST_SIGNATURE_MISSING: This endpoint requires a signed request. Send x-pyrosync-timestamp, x-pyrosync-nonce, and x-pyrosync-signature. See the request signing guide.

REQUEST_SIGNATURE_REPLAY: This nonce was already used. Sign the request again with a new nonce.

REQUEST_SIGNATURE_STALE: The request timestamp is outside the allowed window. Sign a new timestamp within five minutes of the server clock.

TARGET_DISABLED: The target is currently disabled Enable the target, then retry.

TARGET_INVALID_URL: The target URL is not a valid URL Send an http or https URL and retry.

TARGET_NOT_FOUND: The specified scrape target was not found Check the target id and that this workspace owns it.

UNAUTHORIZED: The request is not authorized Send valid credentials or a valid signature and retry.

VALIDATION_ERROR: Request validation failed Fix the fields listed in the error and send the request again.

WEBHOOK_DELIVERY_FAILED: Failed to deliver webhook payload Check the endpoint and retry delivery.

WORKER_OVERLOADED: All workers are at maximum capacity Retry after the queue drains.

WORKER_UNAVAILABLE: No workers are currently available Retry after a worker becomes available.