Error Codes

DocumentPro exposes two API surfaces — the REST API and the MCP server — and they're at different points in adopting structured, machine-readable error codes.

REST API

The REST API returns a structured error_code for exactly two cases. Every other error (400/403/404/500) has no error_code field — match on HTTP status instead.

insufficient_credits (HTTP 400) — account has 0 usable credits:

{
  "success": false,
  "error": "descriptive error message",
  "error_code": "insufficient_credits",
  "credits_remaining": 0,
  "upgrade_url": "https://app.documentpro.ai/plans?pack=starter"
}

page_limit_exceeded (HTTP 400) — document exceeds the page cap for the request. The cap is 100 pages (300 for tax-flagged accounts) and is not plan-dependent:

{
  "success": false,
  "error": "descriptive error message",
  "error_code": "page_limit_exceeded",
  "page_limit": 100
}

For every other error, the response is:

{
    "success": false,
    "error": "descriptive error message"
}

with no code to match on — treat error as an opaque, human-readable string and branch on the HTTP status code instead (see each endpoint's reference page for which statuses apply).

MCP server

The MCP server uses a separate error-code vocabulary from the REST API — different casing, and not a 1:1 mapping (e.g. REST's insufficient_credits is INSUFFICIENT_CREDITS here; REST has no equivalent of DOCUMENT_NOT_READY). Don't conflate the two lists.

{ "error_code": "NOT_FOUND", "message": "Template not found" }

Nine codes today: UNAUTHORIZED, FORBIDDEN, NOT_FOUND, INVALID_INPUT, DOCUMENT_NOT_READY, INSUFFICIENT_CREDITS, SCHEMA_UNAVAILABLE, PAGE_LIMIT_EXCEEDED, INTERNAL_ERROR. NOT_FOUND and SCHEMA_UNAVAILABLE previously had a mapping bug in production (both fell through to INVALID_INPUT) — fixed by PR #1795 (commit 56933f25), released to main on 2026-07-09.

See the MCP Server reference for the full table with descriptions, kept there as the single source of truth to avoid the two pages drifting out of sync.