Dawloom API errors

Every 4xx and 5xx response from the Dawloom API is JSON with the same shape, never an HTML page. The code field is stable and safe to branch on. The type field is a URL that links straight to the section on this page.

The shape

Modelled on RFC 9457 problem details, with two additions: a hint saying what to change, and ok plus error kept for clients written against the older responses. Send Accept: application/problem+json and the response is typed as a problem document instead of plain JSON. The body is identical.

{
  "type": "https://dawloom.com/developers/errors/#rate_limited",
  "title": "Too many requests",
  "status": 429,
  "code": "rate_limited",
  "detail": "The limit is 30 requests per 60 seconds. Retry in 42 seconds.",
  "hint": "Wait for the number of seconds in Retry-After, then retry.",
  "documentation_url": "https://dawloom.com/developers/",
  "instance": "/api/v1/convert",
  "ok": false,
  "error": "rate_limited",
  "retry_after_seconds": 42
}

code: Stable machine-readable identifier. Branch on this, not on the status.
title: The same short summary for every instance of this code.
detail: What went wrong on this particular request. Safe to show a person.
hint: What to change before retrying. Written for whoever has to fix it.
errors: Present on validation failures: one entry per broken field, with a field name, a code, and a message.
instance: The path that produced the error, so logs stay useful.

Every code

invalid_json

HTTP 400

Request body is not valid JSON

Send a JSON object and set Content-Type: application/json.

invalid_request

HTTP 400

Request could not be understood

Check the request body against the OpenAPI schema at https://dawloom.com/api/v1/openapi.json.

validation_failed

HTTP 400

One or more fields failed validation

Fix the fields listed in "errors" and send the request again.

not_found

HTTP 404

No API endpoint at this path

GET https://dawloom.com/api/v1/ for the list of endpoints.

method_not_allowed

HTTP 405

HTTP method not allowed on this endpoint

Check the "allow" field for the methods this endpoint accepts.

payload_too_large

HTTP 413

Payload exceeds the size limit

The limit is 25 MB. Split the document or send a URL instead of the bytes.

unsupported_media_type

HTTP 415

Content-Type is not supported

Use multipart/form-data, application/json, or application/octet-stream.

unprocessable

HTTP 422

The document could not be converted

See "code" for the reason. Encrypted files and image-only PDFs cannot be converted.

rate_limited

HTTP 429

Too many requests

Wait for the number of seconds in Retry-After, then retry.

not_configured

HTTP 503

The endpoint is temporarily not configured

Nothing to fix on your side. Retry later or email support@dawloom.com.

upstream_failed

HTTP 502

An upstream service failed

Retry once. If it keeps failing, email support@dawloom.com.

fetch_failed

HTTP 502

The document URL could not be fetched

Check that the URL is public and returns the file directly.

Errors outside the API

A request for a page that does not exist returns a real HTTP 404. Browsers get the HTML error page. Everything else, including agents and curl, gets a short markdown document that names the requested path and links to the sitemap, llms.txt, and this portal. Nothing on this site ever answers a missing path with a 200.

The MCP server at /mcp uses JSON-RPC error objects instead, with the codes the Model Context Protocol defines: -32700 parse error, -32601 method not found, -32602 unknown tool, -32020 header mismatch, and -32022 unsupported protocol version.

Want error handling this boring?

Predictable errors are a design decision. We make them for the products we build.

Start a project Book a meeting