Skip to main content
The Just Flow It API uses conventional HTTP status codes and returns a consistent JSON error envelope on every failed request. The same envelope shape is used for all 4xx and 5xx responses, so you can write one error handler that works across every endpoint.

​
The error envelope

Every error response has the same JSON shape: 
{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_parameter",
    "message": "Missing required parameter: prompt.",
    "param": "prompt"
  },
  "request_id": "req_8f3c1a9e2b7d4f60"
}
​
error
object
required
The error object describing what went wrong.
​
request_id
string
required
A unique identifier for this request, at the top level of the response (a sibling of error, not nested inside it). Give this to support when reporting a problem.
request_id lives at the top level of the response body. The type, code, message, and param fields live inside error. Do not assume request_id is nested under error.

​
X-Request-Id

Every API response — successful or not — includes an X-Request-Id response header. Its value is the same identifier returned as request_id in the error envelope. These are two surfaces of the same id:
  • X-Request-Id header — present on every response, including 2xx successes and 204 No Content responses that have no body.
  • request_id body field — present in every error envelope.
Always read and log the X-Request-Id header, even on success. If a response has no body (such as a 204 from DELETE) or a malformed body, the header is the only place the id appears.
401 Unauthorized responses also include a WWW-Authenticate: Bearer header.

​
Error types

error.type maps directly to the HTTP status code. The table lists every type, its status, the codes that can appear under it, and what it means.
error.typeHTTP statuserror.code valuesMeaning
invalid_request_error400invalid_json, missing_parameter, invalid_parameter, payload_too_large, invalid_cursorThe request was malformed: unparseable JSON, a missing or invalid parameter, a body that was too large, or a bad/expired pagination cursor.
authentication_error401missing_api_key, invalid_api_key, revoked_api_key, expired_api_keyThe API key is missing, unrecognized, revoked, or expired. Response includes WWW-Authenticate: Bearer.
permission_error403plan_required, insufficient_scopeThe key is valid but not allowed: the plan does not include API access (plan_required), or the key lacks the required scope (insufficient_scope).
not_found_error404resource_not_foundThe requested resource does not exist or is not accessible by this key.
conflict_error409—The request conflicts with the current state of the resource.
validation_error422validation_failedThe request was well-formed but semantically invalid — for example, invalid BPMN 2.0.
rate_limit_error429rate_limit_exceeded, quota_exceededA limit was hit: the per-key request burst limit (rate_limit_exceeded) or the monthly AI generation quota (quota_exceeded). Response includes Retry-After.
api_error500internal_errorSomething went wrong on our side. Retry later and, if it persists, contact support with the request_id.
The Generation resource has its own job-level error object ({ code, message }) that describes why an async generation failed. That is part of a successful 200/202 poll response — it is not the error envelope described on this page.

​
Example error response

A 422 returned when importing invalid BPMN 2.0 to POST /diagrams/import. Note error.param pinpointing the offending field, and request_id at the top level. 
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
X-Request-Id: req_8f3c1a9e2b7d4f60

{
  "error": {
    "type": "validation_error",
    "code": "validation_failed",
    "message": "The provided XML is not valid BPMN 2.0.",
    "param": "bpmn_xml"
  },
  "request_id": "req_8f3c1a9e2b7d4f60"
}

​
Handling errors

# Capture both the body and the X-Request-Id header.
curl -sS -D - -o body.json \
  -X POST https://justflow.it/api/v1/diagrams/import \
  -H "Authorization: Bearer jfi_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "bpmn_xml": "not-valid-bpmn" }' \
  | grep -i "^x-request-id:"

cat body.json

​
Using request_id for support

When something goes wrong and you need help, the request_id lets us locate the exact request in our logs.
1

Capture the id

Read X-Request-Id from the response header (always present), or request_id from the error body. They are the same value.
2

Log it alongside the error

Store the request_id with error.type, error.code, and the HTTP status. Logging it on success too means you can correlate a later report with the originating call.
3

Include it in your report

When contacting support, send the request_id, the endpoint and method, the approximate timestamp, and the error.type / error.code you received.
Include the request_id in every support message. It is the fastest way for us to trace exactly what happened on a specific call.