Skip to content

error-codes.md

Latest commit

 

History

History
87 lines (64 loc) · 6.72 KB

error-codes.md

File metadata and controls

87 lines (64 loc) · 6.72 KB

Error Codes

Complete reference for all error codes returned by the Bytedoc API.

Error Response Format

All errors return a JSON object with an error field containing code and message:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Field 'template_id' is required."
  }
}

The code is a stable, machine-readable identifier you can use for programmatic error handling. The message is human-readable and may change between versions.

Error Codes

Code HTTP Status Description Common Causes Resolution
VALIDATION_ERROR 400 Request body or query parameters failed Zod schema validation. Missing required fields, wrong data types, invalid enum values, malformed JSON body. Check the message field for details on which field failed. Ensure all required fields are present and correctly typed.
INVALID_TEMPLATE_TYPE 400 The template type does not match the requested operation. Using a PDF template with /documents/generate (expects HTML), or an HTML template with /documents/fill (expects PDF), or a non-DOCX template with /documents/fill-docx. Verify the template type matches the endpoint: PDF templates for /fill, HTML templates for /generate, DOCX templates for /fill-docx.
UNAUTHORIZED 401 Authentication failed. Missing Authorization header, malformed header (must be Bearer pk_...), invalid or revoked API key, using a deleted key. Verify the Authorization header format is Bearer pk_live_xxx or Bearer pk_test_xxx. Check that the key has not been deleted in the dashboard.
TEMPLATE_NOT_FOUND 404 The requested template does not exist. Incorrect template ID, template belongs to a different account, template was deleted. Verify the template ID. Use GET /v1/templates to list available templates. Template IDs are prefixed with tpl_.
DOCUMENT_NOT_FOUND 404 The requested document does not exist. Incorrect document ID, document belongs to a different account, document was deleted. Verify the document ID. Use GET /v1/documents to list available documents. Document IDs are prefixed with doc_.
API_KEY_NOT_FOUND 404 The API key ID does not exist. Incorrect key ID when calling DELETE /v1/api-keys/:id, key belongs to a different account. Verify the API key ID. Use GET /v1/api-keys to list your keys. Key IDs are prefixed with ak_.
WEBHOOK_NOT_FOUND 404 The webhook endpoint ID does not exist. Incorrect webhook ID, webhook belongs to a different account, webhook was deleted. Verify the webhook ID. Use GET /v1/webhooks to list your endpoints.
DOCUMENT_EXPIRED 410 The document retention period has passed and the file has been deleted. Attempting to download a document after its expires_at timestamp. Retention varies by plan (Free: 7d, Starter: 30d, Pro: 90d, Business: 365d, Enterprise: unlimited). Re-generate or re-fill the document. Download documents before they expire, or upgrade your plan for longer retention.
USAGE_LIMIT_EXCEEDED 429 Monthly document generation limit reached for the current plan. Exceeded the monthly document quota for your plan tier. Sandbox keys have a 60 documents/day limit. Upgrade to a higher plan for more monthly documents, or wait for the next billing period. Check current usage at GET /v1/usage.
RATE_LIMIT_EXCEEDED 429 Too many requests in a short time window. Sending requests faster than the allowed rate. Sandbox keys are limited to 60 requests/minute. Implement exponential backoff. Wait for the duration specified in the Retry-After response header before retrying.
INTERNAL_ERROR 500 An unexpected server error occurred. Server-side issue, temporary infrastructure problem, unexpected input that bypassed validation. Retry the request with exponential backoff. If the error persists, contact support with the request details and timestamp.

HTTP Status Codes

Quick reference for all HTTP status codes used by the API:

Status Meaning When Used
200 OK Request succeeded. GET requests, updates, deletes.
201 Created Resource created successfully. POST requests that create templates, documents, API keys, or webhooks.
400 Bad Request Invalid request. Validation errors, wrong template types.
401 Unauthorized Authentication failed. Missing or invalid API key.
404 Not Found Resource not found. Template, document, API key, or webhook does not exist.
410 Gone Resource permanently unavailable. Expired documents past their retention period.
429 Too Many Requests Rate or usage limit exceeded. Too many requests per minute, or monthly quota reached.
500 Internal Server Error Server error. Unexpected failures.

Sandbox Mode Limits

API keys with the pk_test_ prefix operate in sandbox mode with stricter limits:

Constraint Sandbox (pk_test_) Production (pk_live_)
Rate limit 60 requests/minute Plan-based
Daily document limit 60 documents/day Plan-based monthly limit
Document retention 1 hour Plan-based (7d to unlimited)
Output watermark Yes (diagonal "SANDBOX" watermark) No
Webhooks Disabled Enabled (Pro+ plans)

Sandbox mode is designed for development and testing. Documents created with test keys are watermarked and automatically deleted after 1 hour. Webhook endpoints are not triggered for sandbox documents.

Sandbox-Specific Errors

When operating in sandbox mode, you may encounter these limits sooner:

  • USAGE_LIMIT_EXCEEDED — Triggered after 60 documents in a single day (resets at midnight UTC), rather than the monthly plan limit.
  • RATE_LIMIT_EXCEEDED — Triggered after 60 requests/minute, regardless of plan.
  • DOCUMENT_EXPIRED — Documents expire after 1 hour instead of the plan-based retention period.

Error Handling Best Practices

  1. Always check the HTTP status code first. A 2xx response means success; anything else is an error.

  2. Parse the error response body. Extract error.code for programmatic handling and error.message for logging or user display.

  3. Implement retry logic for transient errors. 429 and 500 errors are often temporary. Use exponential backoff:

    • First retry: 1 second
    • Second retry: 2 seconds
    • Third retry: 4 seconds
    • Maximum: 3 retries

  4. Do not retry 4xx errors (except 429). A 400, 401, 404, or 410 response indicates a client-side issue that must be fixed before retrying.

  5. Log error details. Include the timestamp, endpoint, request body (without sensitive data), and the full error response for debugging.