Error Handling

Parselyze exposes errors in two different ways:

1. HTTP-level errors for auth, rate limits, invalid requests, and some hard failures
2. In-result errors for many document extraction failures on the synchronous API

That distinction is important when integrating the API.

1. HTTP-Level Errors

These stop the request before you get a parse result.

Common status codes:

Status	When it happens
400	Missing file, invalid fileUrl, malformed request body
401	Missing or invalid API key
403	Quota exceeded or plan restriction
429	Rate limit exceeded
500	Async submission failure or internal processing failure

Example:

{
  "statusCode": 429,
  "message": "Rate limit exceeded. You can make 10 requests per minute with your FREE plan.",
  "error": "Too Many Requests",
  "retryAfter": 60
}

2. Synchronous In-Result Errors

For synchronous parsing, many extraction failures still return 200 OK, but the payload contains an error message.

Single Document

{
  "result": {
    "error": "No text could be extracted from the document."
  },
  "pageCount": 1,
  "pageUsed": 0,
  "pageRemaining": 999
}

Multiple Documents

{
  "results": [
    {
      "filename": "doc-1.pdf",
      "result": {
        "error": "Document could not be read."
      }
    },
    {
      "filename": "doc-2.jpg",
      "result": {
        "invoice": {
          "number": "INV-2025-002"
        }
      }
    }
  ],
  "pageCount": 3,
  "pageUsed": 2,
  "pageRemaining": 998
}

3. Async Failures

For async processing:

• job submission can fail with an HTTP error
• a submitted job can later move to failed
• webhooks can deliver a document.failed event

Example async job failure:

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "fileName": "invoice.pdf",
  "templateId": "YOUR_TEMPLATE_ID",
  "result": null,
  "error": "Document could not be read.",
  "pageCount": 12,
  "attempts": 3,
  "createdAt": "2026-03-31T10:30:00Z",
  "startedAt": "2026-03-31T10:30:05Z",
  "completedAt": "2026-03-31T10:31:45Z"
}

Known Product Limits to Handle Explicitly

Your integration should expect these current limits:

• Free users cannot process multiple documents in one sync request
• The async API accepts one file per job
• Scanned PDFs over 30 pages are not supported yet

Integration Recommendations

• Always check HTTP status first
• On sync responses, also inspect result.error or each results[i].result.error
• On async flows, check status and error
• Treat webhook deliveries as idempotent events
• Implement retries only for transport-level failures, not for a valid parse response that already contains result.error