Every Projul AI Connect error is JSON: a status number, a short code, a message, and, for validation problems, the field and reason. This page lists every code and what to do.
In this article
413 and 415: the request envelope
What an error looks like
{
"type": "https://connect.projul.com/errors/validation_failed",
"title": "Validation failed",
"status": 422,
"detail": "The request was well-formed but could not be accepted.",
"code": "validation_failed",
"request_id": "req_6ErEg3xmkg2fdk0dh34e2O",
"errors": [
{"field": "/status", "code": "invalid_enum", "message": "'Active' is not a writable project status. Accepted values: new_lead,..."}
]
}
The request_id identifies the exact request in Projul's logs.
400: bad requests
invalid_request: a malformed request, unknown field, wrong type, missing required header, or a bad version value; the detail names it. Fix it, don't just retry. invalid_cursor: the page cursor was tampered with or issued under different filters or sort; start over. bulk_limit_exceeded: a bulk list, such as line items, exceeded the 200-item limit. A missing field is 422, not 400.
401 and 403: the key
401 invalid_api_key: no key, unknown key, or revoked key, one code for all three. 403: insufficient_access (valid key, wrong permission); key_paused (the key's user was deactivated); account_inactive, feature_not_enabled, connect_suspended (account, plan, or Connect access doesn't allow calls). Check the first two under "Settings" and "Projul AI Connect"; the rest need support. See Should I give my AI a Read key or a Read-Write key?
404 not_found
not_found: the record doesn't exist, was deleted, is an archived client, or belongs to another company, Projul won't say which. Archived projects and clients stay readable by id and can be unarchived by id. A 404 on a path means no such operation.
405 method_not_allowed
method_not_allowed: the path exists but not for that operation; the response names what it does support.
409: conflicts
resource_archived: matches an existing, usually archived client; the detail gives its id and unarchive address, unarchive, retry with the same idempotency key (your AI's create-dedupe label); no address, no fix. not_draft: the estimate was sent, approved, rejected, or closed, so it's no longer API-editable; add a change order. estimate_exists: the project already has a real estimate. deletion_blocked: the invoice has a recorded payment. idempotency_in_flight: the same create is still running. idempotency_target_deleted: a create replayed after deletion. concurrency_conflict: a competing write lost a uniqueness race; retry alone. steps_not_supported_on_recurring: a checklist sent for a repeating task.
412 and 428: version errors
412 stale_version: the record changed since you read it; read it again and reapply. 428 precondition_required: the required version was missing, or a wildcard ("any version") was sent instead; send back the version you read. See What do "version" and "stale" errors mean?
413 and 415: the request envelope
413 payload_too_large: the body is over the size limit, usually too many bulk items; send smaller batches. 415 unsupported_media_type: the request wasn't sent as application/json.
422 validation_failed
A value was unacceptable; the errors list names the field and reason: invalid_enum (outside the allowed list, in the message); unknown_reference (an id missing or belonging elsewhere); required (needed here, e.g. a start date on a dated template); out_of_range (e.g. likelihood outside 0 to 100); mutually_exclusive (e.g. client id with inline client); tax_level_mismatch; tax_rate_retired or discount_retired (newly applied); too_large and size_mismatch (uploads); scheme_not_https (webhook); empty_team (no members). Two answer 422 as the response's own code, not a list entry: file_too_large (upload over your limit) and idempotency_key_reuse (same key, different body; use a new one).
429: rate limits and quota
rate_limited: too many requests from your keys, or too many uploads; the response says how long to wait. quota_exceeded, also 429: your monthly Connect quota is used up; the response carries quota_limit, quota_used, and quota_resets_at. See Why does my AI say "too many requests" or slow down?
500 and 503: Projul's side
500 internal_error: Projul's side failed, not your request; retry once, and if it repeats, the request_id identifies it. 503 idempotency_store_unavailable: Projul couldn't reach the store that prevents duplicate creates, so nothing was created; retry with the same idempotency key shortly.
Questions? Let's Chat.
support@projul.com
(844) 776-5853