Skip to content
Notificado
Menu
Create account

Errors

How to read a refusal from Notificado (code, cause and fix) and the codes you will meet most often.

Updated:

Every refusal has the same three parts:

Part What it is
code Stable, X_SCREAMING_SNAKE. Branch on it, never on the wording.
cause What was wrong, in words.
fix The next step that ends it; usually literal.

Over HTTP they arrive as application/problem+json with a status; over MCP, as a tool result with isError, or as an HTTP answer (401, 413, 429) with the same body.

{
  "type": "urn:ultimate:error:X_CASE_RADICADO_TAKEN",
  "title": "case radicado taken",
  "status": 409,
  "code": "X_CASE_RADICADO_TAKEN",
  "cause": "this org already has open case <caseId> for radicado 05001310300320260012300",
  "fix": "use the existing case — getCase({ orgId, caseId: '<caseId>' }) — instead of opening a second one; to replace it with corrected data, createCase({ …, correctionOf: '<caseId>' }) archives it and opens the corrected case",
  "requestId": "<requestId>"
}

Quote the requestId when you write to admin@notificado.co.

The API's own answers (/v1)

Status Code What to do
401 X_UNAUTHENTICATED No token, or one that is unknown, expired or revoked. Issue a new one at /cuenta/api.
404 X_ROUTE_NOT_FOUND The operation does not exist or is outside the token's scopes. Check the path, then the scopes.
404 X_NOT_FOUND A single-object read (get-case, get-notification, get-send-confirmation, get-import) found no such id in your firm: it does not exist, belongs to another firm or was deleted. The operation does exist and the token does reach it. Do not retry with the same id; look it up in the list.
400 X_INPUT_INVALID Also when a limit or a _first is above the list's maximum: it is refused, never cut down. cause names the field and the maximum; the maximums are in Limits. Ask for fewer rows and continue with nextCursor.
400 X_CURSOR_INVALID The cursor is not this list's: it comes from another list, other filters or another order, it was edited, or the key that signs it changed. Also an exportNotifications cursor sent with filters other than the first call's. Ask for the first page again, with no cursor.
422 X_PAGE_LIMIT_INVALID A page size outside its bounds reached the read itself. Each operation's schema usually stops it first, with 400 X_INPUT_INVALID; both refusals mean the same: nothing is ever cut down. Ask for at most the ceiling cause names and continue with the cursor.
422 X_DEADLINE_CURSOR_CONFLICT listDeadlines got cursor and after with different values. after is the earlier name of cursor: send cursor alone.
409 X_IDEMPOTENCY_CONFLICT That Idempotency-Key names another body, or its first attempt is still running. See Idempotent retries.
400 X_IDEMPOTENCY_KEY_INVALID An empty key, or one longer than 255 characters.
429 X_RATE_LIMITED Over the per-token limit; wait Retry-After seconds.

The two 404s differ by code: X_ROUTE_NOT_FOUND is about the operation, X_NOT_FOUND about the object you asked for.

Every code the API can answer, with its HTTP status, what it means and what to do, is in the error catalog, each under its own anchor: /docs/api/errores#x-case-radicado-taken.

Common codes

Code What to do
X_INPUT_INVALID / X_BODY_INVALID A field fails the schema; the issues list names each one.
X_FORBIDDEN Your role does not allow the action, or the orgId is not your firm's.
X_CSRF_BLOCKED A write to the panel's routes with a cookie and no origin. Never on /v1, which takes no cookie; see Authentication.
X_KYC_REQUIRED Your lawyer verification is not approved; finish it in the panel.
X_CASE_RADICADO_TAKEN The case already exists; look it up instead of creating another.
X_CASE_RADICADO_INVALID The radicado is not a valid 23-digit number.
X_NOTIFICATION_NOT_DRAFT The notification was already sent; it cannot be edited or re-sent.
X_NOTIFICATION_NO_RECIPIENTS Recipients are missing; add them in the panel.
X_NOTIFICATION_NO_ATTACHMENTS Attach at least one document.
X_JURAMENTO_REQUIRED / X_PROVENANCE_REQUIRED An address's sworn statement or provenance is missing.
X_ATTACHMENTS_TOO_LARGE Attachments exceed 6 MB in total. Compress the PDFs or split them across more than one notification.
X_ATTACHMENT_DUPLICATE That document is already attached; carry on.
X_CREDITS_INSUFFICIENT Not enough credits. With meta.mode = paid (sales are on since 30 September 2026), buy a pack at /creditos. With meta.mode = free, the deployment sells no credits: your free sends are used up and you can write to admin@notificado.co (Notificado staff can grant you credits).
X_PAYMENT_CHECKOUT_DISABLED Online checkout is not ready yet (free mode); nothing can be bought for now. Do not retry.
X_SEND_CONFIRMATION_EXPIRED Nobody confirmed the send within 24 hours; nothing was sent.
X_SEND_CONFIRMATION_TOKEN_REVOKED The token or connection the agent asked with was revoked before the confirmation; nothing was sent. Send it yourself from the draft, or have the agent ask again over a live connection.
X_CONSTANCIA_NOT_FOUND No constancia yet: it is issued once delivery events arrive.
X_EVIDENCE_ZIP_NOT_READY The package is still being built; retry once after 30 seconds.
X_MCP_SCOPE_DENIED The token lacks that tool's scope.
X_MCP_RATE_LIMITED Too many calls; wait as long as retry-after says.

Retries

Never repeat a refused call unchanged. Only *_NOT_READY answers, rate limits and network failures are retried, after waiting; a create is retried with the same Idempotency-Key (Idempotent retries).

Assistants have the same list in the MCP server's docs://guides/errors guide.