Error Codes

Every error response returned by the Re:port Flow API (PDF generation, status, download, template parameters) contains a machine-readable code (the exception: a 413, or a 504 / 524 on sync generation, may come from the path in front of the API, in which case the body is not necessarily JSON and has no code; detect those by the status code, see Limitations). message is a human-readable explanation that changes with the language setting and may be reworded in the future, so branch on code in your code. Each code is described on this page at #<code in lowercase> (for example #plan_page_limit_exceeded), which is exactly where the response's docsUrl points.

For per-status handling and retry implementations, see Error Handling.

Error response shape

{
  "statusCode": 403,
  "code": "PLAN_PAGE_LIMIT_EXCEEDED",
  "message": "Monthly page limit reached (100 pages). Upgrade your plan or wait until next month.",
  "error": "Forbidden",
  "details": [],
  "docsUrl": "https://doc.re-port-flow.com/en/docs/guides/error-codes#plan_page_limit_exceeded"
}

Field	Type	Description
statusCode	number	HTTP status code
code	string	Error code (the headings on this page). Existing values are never renamed or removed (new ones may be added)
message	string / string[]	Human-readable explanation. Usually a string; see "When message is an array" below
error	string	HTTP reason phrase (Bad Request, Forbidden, …)
details	array	Per-field details. Empty array [] when there are none
docsUrl	string	URL of this page's section for the code
retryAfter	number	Only on 429 RATE_LIMITED and 409 FILE_NOT_READY: seconds to wait before retrying

Language (Accept-Language)

• The default is English.
• Only when the highest-priority (q-value) language tag in the request's Accept-Language is ja or ja-* (e.g. ja-JP) are message and details[].message returned in Japanese where a Japanese translation exists, with docsUrl pointing to the Japanese page (https://doc.re-port-flow.com/docs/guides/error-codes#<code>).
• Messages without a Japanese translation stay in English even with ja. Examples: the message of FILE_NOT_READY, FILE_GENERATION_FAILED, REQUEST_NOT_FOUND and WEBHOOK_URL_NOT_ALLOWED, the standard input-validation (VALIDATION_FAILED) messages (such as version must be an integer number), and the generic 500 message (Internal Server Error).
• Everything else (missing, *, English, any other language) gets English.
• The response header Content-Language: en / Content-Language: ja tells you which language was used.
• code is the same regardless of language.

curl -X POST https://api.re-port-flow.com/v1/file/sync/single \
  -H "appkey: your-application-key" \
  -H "Content-Type: application/json" \
  -H "Accept-Language: ja" \
  -d '{ ... }'

When message is an array

For request-body validation errors (missing required fields, wrong types, forbidden file-name characters, …), message stays an array of strings for compatibility with existing clients. The code is then usually VALIDATION_FAILED; when every element is the same kind of error (for example only forbidden file-name characters), it is that kind's code (for example FILE_NAME_INVALID). For all other errors message is a string.

If you don't want to depend on the type of message, use code and details.

details

details is an array of objects shaped like this:

Field	Description
field	Where the problem is. May be omitted. Examples: version, content.fileName, contents.0.fileName, params.amount
expected	The expected type. May be omitted. For params type mismatches: string / number / date / boolean / object / array
code	A per-item error code, included only when it can be determined
message	Description of that item

{
  "statusCode": 400,
  "code": "PARAMS_TYPE_MISMATCH",
  "message": "Parameter validation failed: \"amount\" must be a number",
  "error": "Bad Request",
  "details": [
    { "field": "params.amount", "expected": "number", "code": "PARAMS_TYPE_MISMATCH", "message": "\"amount\" must be a number" }
  ],
  "docsUrl": "https://doc.re-port-flow.com/en/docs/guides/error-codes#params_type_mismatch"
}

retryAfter and Retry-After

On 429 (RATE_LIMITED) and 409 (FILE_NOT_READY), the Retry-After response header and the body's retryAfter both hold the number of seconds to wait before retrying (same value). After waiting that long you can resend the same request unchanged.

message on 5xx

The message of a 5xx is a generic text without internal details such as stack traces (for example Internal Server Error). If it persists, contact support with the time of the error and the request you sent.

Code list (summary)

code	Typical HTTP status	Summary
AUTH_HEADER_MISSING	412	Neither an appkey nor an Authorization header, or the appkey header is malformed
INVALID_CREDENTIALS	401	Application key or token is invalid
WORKSPACE_MISMATCH	403	Thumbnail generation: the request's workspaceId does not match the credentials' workspace
WORKSPACE_SCOPE_VIOLATION	403	Output target outside the authenticated workspace
WORKSPACE_ROLE_DENIED	403	The OAuth user has no permission in the workspace
PLAN_NOT_FOUND	403	Workspace plan information is missing
ACCESS_DENIED	403	Access denied (not returned by the generation or download endpoints)
PLAN_PAGE_LIMIT_EXCEEDED	403	Monthly output page limit reached
ACTIVE_PLAN_NOT_FOUND	404	No active plan for the workspace
RATE_LIMITED	429	Rate limit exceeded
DESIGN_NOT_FOUND	404	Get parameters (without version): the template does not exist
DESIGN_VERSION_NOT_FOUND	404	Generation / get parameters (with version): the template or the version does not exist
VERSION_NOT_FOUND	404	Not returned by the generation or parameter endpoints
VALIDATION_FAILED	400	Request body validation error
PARAMS_TYPE_MISMATCH	400	A params value has the wrong type for the template
PARAMS_NOT_OBJECT	400	params / passthrough is not a JSON object
PARAMS_CIRCULAR_REFERENCE	400	params contains a circular reference
PARAMS_TOO_LARGE	400	params is too large
FILE_NAME_INVALID	400	Forbidden characters in the file name
FILE_NAME_DUPLICATED	400	Duplicate file names in contents
TOO_MANY_CONTENTS	400	More than 100 items in contents
WEBHOOK_URL_NOT_ALLOWED	400	webhookUrl is not a registered, enabled endpoint
REQUEST_NOT_FOUND	404	Status API: requestId not found (wrong ID, another workspace, expired record, deleted)
FILE_NOT_FOUND	404	Download: wrong ID, another workspace's ID, a single generation that failed more than 24 hours ago, or deleted output
FILE_NOT_READY	409	Download: still generating
FILE_GENERATION_FAILED	422	Download: the generation failed
JOB_NOT_FOUND	404	Job not found
RENDER_QUEUE_FULL	503	The generation queue is full
CONVERT_QUEUE_FULL	503	The image conversion / AI estimation queue is full (in-app features)
PARTIAL_FAILURE	(file.failed webhook only)	Some files of a multiple request failed
GENERATION_INTERRUPTED	(status API only)	The generation process stopped

There are also codes used by in-app features (such as PDF_CONVERSION_FAILED) and generic codes for errors without a specific code (such as BAD_REQUEST).

Authentication and authorization

AUTH_HEADER_MISSING

• HTTP status: 412 Precondition Failed
• Cause: Neither an appkey header nor an Authorization: Bearer <token> header was sent, or an appkey header was sent but its value failed format validation.
• Fix: Send one of the two with a valid value (see API Keys / OAuth 2.0).

Why it stays 412

A missing authentication header keeps returning 412 for compatibility with existing clients (it was not changed to 401). Use code to tell it apart from a 401.

INVALID_CREDENTIALS

• HTTP status: 401 Unauthorized
• Cause: The application key or access token is invalid. This includes a token without the required scope (pdf:generate) or one not tied to a workspace. It is also returned when you send an x-workspace-id header whose value does not match the application key's workspace.
• Fix: Check the key (and whether it was regenerated), and the token's expiry and scope.

WORKSPACE_MISMATCH

• HTTP status: 403 Forbidden
• Cause: The workspaceId in a thumbnail generation request body does not match the credentials' workspace. The PDF generation, status, download and parameter endpoints never return this code (an x-workspace-id header mismatch is 401 INVALID_CREDENTIALS).
• Fix: Specify the same workspace as the key or token you authenticate with (if omitted, the credentials' workspace is used).

WORKSPACE_SCOPE_VIOLATION

• HTTP status: 403 Forbidden
• Cause: The output target is outside the authenticated workspace.
• Fix: Output to the authenticated workspace.

WORKSPACE_ROLE_DENIED

• HTTP status: 403 Forbidden
• Cause: The user who authorized via OAuth has no permission for this operation in the workspace.
• Fix: Ask a workspace admin to check the user's role.

PLAN_NOT_FOUND

• HTTP status: 403 Forbidden
• Cause: The workspace's plan information could not be found.
• Fix: Check Workspace settings → Plan in the dashboard. Contact support if that doesn't help.

ACCESS_DENIED

• HTTP status: 403 Forbidden
• Cause: Access was denied. The code is still in the code list, but the PDF generation, status and download endpoints do not currently return it. Downloading another workspace's requestId returns 404 FILE_NOT_FOUND (404 REQUEST_NOT_FOUND on the status API) so that its existence is not revealed.
• Fix: If you receive it, contact support with the time of the error and the request you sent.

Plan and rate limits

PLAN_PAGE_LIMIT_EXCEEDED

• HTTP status: 403 Forbidden
• Cause: This month's PDF output page limit was reached (the limit counts total output pages, not requests). The English message is Monthly page limit reached (<limit> pages). Upgrade your plan or wait until next month.
• Fix: Upgrade the plan or wait until next month. Retrying within the same month will not succeed.

ACTIVE_PLAN_NOT_FOUND

• HTTP status: 404 Not Found
• Cause: The workspace has no active plan.
• Fix: Check the plan status in the dashboard.

RATE_LIMITED

• HTTP status: 429 Too Many Requests
• Cause: The per-workspace rate limit was exceeded (sync generation 30 req/min; async generation, download and others 100 req/min; status API 300 req/min — see Limitations).
• Fix: Wait for the number of seconds in the Retry-After header (the body's retryAfter is the same value), then resend.

Templates

DESIGN_NOT_FOUND

• HTTP status: 404 Not Found
• Cause: On Get Template Parameters without version, the template ID (designId) does not exist (or belongs to another workspace). A template ID is a 16-character alphanumeric string such as 0eUDdgAjNXrrItA2; its format is not checked, so a wrong ID returns a 404 rather than a 400. On PDF generation and on parameter fetches with version, an unknown designId returns DESIGN_VERSION_NOT_FOUND instead.
• Fix: Copy the template ID from the dashboard again.

DESIGN_VERSION_NOT_FOUND

• HTTP status: 404 Not Found
• Cause: On PDF generation, or a parameter fetch with version, the template + version combination does not exist. This covers both a designId that does not exist (or belongs to another workspace) and a version that does not exist.
• Fix: Check the designId and version pair. To check only the designId, call Get Template Parameters without version (a missing template returns DESIGN_NOT_FOUND).

VERSION_NOT_FOUND

• HTTP status: 404 Not Found
• Cause: The code is still in the code list, but the PDF generation and parameter endpoints do not currently return it. A version that does not exist returns DESIGN_VERSION_NOT_FOUND.
• Fix: If you receive it, contact support with the time of the error and the request you sent.

Input

VALIDATION_FAILED

• HTTP status: 400 Bad Request
• Cause: Request body validation failed (missing required fields, wrong types, properties that are not allowed, …). message is an array of strings.
• Fix: Fix the fields pointed to by details[].field.

PARAMS_TYPE_MISMATCH

• HTTP status: 400 Bad Request (for async generation: error.code in the status API, and in the file.failed webhook when the generation request specified webhookUrl)
• Cause: A params value does not match the type of the template's parameter.
• Fix: Use details[].field (params.<key>) and details[].expected to fix the value. You can check each parameter's type with Get Template Parameters.

PARAMS_NOT_OBJECT

• HTTP status: 400 Bad Request
• Cause: params or passthrough is not a JSON object (an array, a string, a JSON string that cannot be parsed, …).
• Fix: Send an object of the form { "key": value }.

PARAMS_CIRCULAR_REFERENCE

• HTTP status: 400 Bad Request
• Cause: params contains a circular reference.
• Fix: Use a non-circular structure.

PARAMS_TOO_LARGE

• HTTP status: 400 Bad Request
• Cause: params exceeds the size limit (1,000,000 bytes).
• Fix: Reduce the data or split the request.

FILE_NAME_INVALID

• HTTP status: 400 Bad Request
• Cause: fileName contains / \ : * ? " < > | or a control character (0x00–0x1F). Spaces and Japanese are allowed.
• Fix: Remove or replace those characters (e.g. fileName.replace(/[\/\\:*?"<>|\x00-\x1F]/g, '_')).

FILE_NAME_DUPLICATED

• HTTP status: 400 Bad Request
• Cause: fileName values in a multiple request's contents are not unique (compared case-insensitively).
• Fix: Give each file a unique name.

TOO_MANY_CONTENTS

• HTTP status: 400 Bad Request
• Cause: contents exceeds the per-request limit (100 items).
• Fix: Split the request.

WEBHOOK_URL_NOT_ALLOWED

• HTTP status: 400 Bad Request
• Cause: The request's webhookUrl does not match the URL of an enabled webhook endpoint registered in the workspace.
• Fix: Register and enable it as a webhook endpoint first (see Webhook Notifications).

Generation and retrieval

REQUEST_NOT_FOUND

• HTTP status: 404 Not Found
• Cause: The requestId given to the status API was not found. You get this code when:
  • the requestId is wrong or belongs to another workspace
  • a single request failed more than 24 hours ago (the job record has expired, and a failed request has no file record)
  • right after generating, the request's job record could not be saved (it returns 404 while still in progress; re-check once or twice a few seconds apart)
  • the files were generated successfully but later deleted, and none are left
  • A multiple request in which every file failed is not a 404 even after 24 hours: it returns 200 status: "failed" (error.code FILE_GENERATION_FAILED, without per-file reasons)
• Fix: Make sure you use the requestId from the generation response and the credentials of the workspace that generated it.

FILE_NOT_FOUND

• HTTP status: 404 Not Found
• Cause: The requestId / fileId given to a download endpoint was not found. A 404 means the ID is wrong, belongs to another workspace (a 404 rather than a 403, so that its existence is not revealed), a single generation that failed more than 24 hours ago (a failed single generation has no file record and its job record is kept for 24 hours, so the failure can no longer be detected), or the output was deleted after a successful generation. Still generating is normally 409 FILE_NOT_READY and a failed generation 422 FILE_GENERATION_FAILED, but a request that is still generating returns 404 when its job record is missing (for example, saving the record failed).
• Fix: Make sure you use the requestId / fileId from the generation response and the credentials of the workspace that generated it. You can also check the request with the status API.

FILE_NOT_READY

• HTTP status: 409 Conflict
• Cause: The file you are downloading is still being generated.
• Fix: Wait for Retry-After (currently 2 seconds) and resend, or wait for completion with the status API.

FILE_GENERATION_FAILED

• HTTP status: 422 Unprocessable Entity (download). Also used as error.code in the status API (and in the file.failed webhook when the generation request specified webhookUrl)
• Cause: PDF generation for the request failed. Also used when every file of a multiple request failed.
• Fix: Check the reason in error / failedFiles of the status API, fix the cause, and generate again as a new request.

JOB_NOT_FOUND

• HTTP status: 404 Not Found
• Cause: The job given to /v1/jobs/{id} was not found.
• Fix: Check the job ID.

RENDER_QUEUE_FULL

• HTTP status: 503 Service Unavailable
• Cause: PDF generation is busy and the queue is full.
• Fix: Retry after a while.

PARTIAL_FAILURE

• HTTP status: none (never an HTTP error response)
• Cause: Only some files of a multiple request (/v1/file/async/multiple) failed. Only when the generation request specified webhookUrl, it appears as error.code of the file.failed webhook sent to that URL, whose files then lists only the failed files (see Webhook Notifications). The files that succeeded are notified with file.completed. In the status API the request stays status: "completed" and the failed files are listed in failedFiles.
• Fix: Fix and regenerate only the failed files.

GENERATION_INTERRUPTED

• HTTP status: none (error.code in the status API only)
• Cause: The generation process stopped without progress (no progress for more than 30 minutes).
• Fix: Generate again with the same content. Contact support if it keeps happening.

Codes used by in-app features

These are normally not returned by the generation endpoints you call from the API; they are used by in-app features such as the editor.

CONVERT_QUEUE_FULL

HTTP 503. Image conversion / AI estimation has reached its concurrency limit and its queue is full. Retry after a while. This is separate from the PDF generation queue (RENDER_QUEUE_FULL).

PDF_CONVERSION_FAILED

Conversion to PDF failed. Retry after a while and contact support if it persists.

OUTPUT_TARGET_MISSING

No output target (outputCategory or outputPath) was specified.

EMPTY_PDF

The PDF data was empty.

INVALID_PDF

The file is not a valid PDF.

THUMBNAIL_ENQUEUE_FAILED

Queuing the thumbnail job failed. Retry after a while.

Generic codes

Errors without a specific code get a generic code based on the HTTP status. A 4xx not listed here is treated as BAD_REQUEST, a 5xx as INTERNAL_ERROR.

BAD_REQUEST

HTTP 400. The request is invalid.

UNAUTHORIZED

HTTP 401. Authentication failed.

FORBIDDEN

HTTP 403. You do not have permission to perform this operation.

NOT_FOUND

HTTP 404. The requested resource was not found.

REQUEST_TIMEOUT

HTTP 408. The request timed out. Use the async endpoints for heavy documents.

CONFLICT

HTTP 409. The request conflicts with the current state.

PRECONDITION_FAILED

HTTP 412. A required request header is missing or invalid.

PAYLOAD_TOO_LARGE

HTTP 413. The request body is too large.

UNPROCESSABLE_ENTITY

HTTP 422. The request could not be processed.

CLIENT_CLOSED_REQUEST

HTTP 499. The client closed the request.

INTERNAL_ERROR

HTTP 500. Internal server error. Retry after a while and contact support if it persists.

SERVICE_UNAVAILABLE

HTTP 503. The service is temporarily unavailable. Retry after a while.