Error catalog
166 codes the /v1 API and the MCP server can answer, each with its HTTP status, what it means and what to do.
Every refusal is application/problem+json with a stable code. Each code below has its own link: the code X_CASE_RADICADO_TAKEN is at #x-case-radicado-taken, lowercase with hyphens.
How to read a refusal, and when to retry: Errors and codes · Idempotent retries · Back to the API reference
| Code | HTTP | What it means | What to do |
|---|---|---|---|
X_ADDRESS_BLOCKED | 422 | The e-mail address cannot receive the notification: it is malformed, disposable, or its domain takes no mail. | Correct the address or use another one the person uses; the panel shows the verdict when the recipient is added. |
X_AGENT_TOKEN_SCOPE_BEYOND_ROLE | 403 | A scope was requested that the issuer’s role does not hold; a token can never do more than whoever issued it. | Ask only for your role’s scopes (/cuenta/api lists them), or have an owner of the firm issue the token. |
X_AGENT_TOKEN_WRONG_ENDPOINT | 403 | A token of another population was presented to this endpoint: a firm token opens /mcp and /v1, an affiliate token /mcp/afiliados and /v1/afiliados, a staff token /mcp/admin. | Use the endpoint the message names, or issue a token of the right population (/cuenta/api for the firm, /afiliados for affiliates). |
X_API_ACCESS_PLAN_REQUIRED | 403 | The firm's plan does not include API and MCP access: it comes with Firma Pro (and a Cobranza contract), never with the trial, credit packs, Abogado or Firma. | An owner upgrades at /facturacion. The same token works again at once; nothing to reissue. |
X_ATTACHMENTS_TOO_LARGE | 413 | The notification’s attachments add up to more than 6 MB. | Remove or compress an attachment so the total stays at or under 6 MB, or split the documents across more than one notification. |
X_ATTACHMENT_DUPLICATE | 409 | That same document (the same SHA-256) is already attached to the notification. | No need to attach it again; carry on. |
X_AUTH_ACCOUNT_REQUIRED | 409 | This action needs a password on the account, and the account has none yet (for example, it signs in with Google only). | Set a password at /cuenta/seguridad and retry. |
X_AUTH_CONFIRM_BROWSER_INVALID | 401 | The confirmation link was opened in a different browser from the one that created the account, or that browser's marker expired. | Open the link in the browser you signed up with, or confirm by typing the password you chose at sign-up. |
X_AUTH_CONFIRM_PASSWORD_INVALID | 401 | The password does not match the one chosen when the account was registered; the confirmation link is still unused. | Type the sign-up password, or continue without it: that password is removed and you can set another at /cuenta/seguridad. |
X_AUTH_CURRENT_PASSWORD_INVALID | 403 | The current password is not correct. | Type the password you sign in with and retry; several failed attempts lock the account for a while. |
X_AUTH_EMAIL_CHANGE_INVALID | 401 | The email change link is not valid, was already used or has expired. | Request the change again at /cuenta/correo. |
X_AUTH_EMAIL_UNCHANGED | 422 | The new email is the one the account already has. | Type a different address in `newEmail`. |
X_AUTH_REAUTH_UNAVAILABLE | 409 | The account has no way to confirm its identity again: neither a password nor an authenticator app. | Set a password or turn on two-step verification at /cuenta/seguridad and retry. |
X_AUTH_RECENT_AUTH_REQUIRED | 403 | This action asks you to confirm your identity again: the authenticator app code or the password. | Retry sending `code` (or `password` without two-step verification). A token cannot do this action: do it from the panel. |
X_AUTH_SIGN_IN_PENDING_INVALID | 401 | The sign-in step that asks for the code expired or was already used. | Sign in again with your email and password; the code page opens again for 15 minutes. |
X_BODY_INVALID | 422 | The request body is not valid JSON, or is larger than the API accepts (1 MB). | Send a JSON object with `content-type: application/json`. Files never go in the body: use requestUpload. |
X_CALENDAR_MISSING_YEAR | 503 | The holiday calendar does not have the year the term computation needs yet. | Retry in a few minutes: the missing year loads by itself. If it persists, write to admin@notificado.co. |
X_CALENDAR_YEAR_OUT_OF_RANGE | 422 | The year asked for is outside the range the holiday calendar covers. | Use a date inside the range the message names. |
X_CAPTCHA_FAILED | 403 | The captcha provider rejected the token: expired, already used, or issued for another site. | Solve the captcha again and retry with the new token; each token works once. |
X_CAPTCHA_REQUIRED | 400 | The anonymous lookup carried no captcha token while captcha is on. | Solve the captcha on /verificar and send its token, or look up with an API token: an authenticated call is not asked. |
X_CAPTCHA_UNAVAILABLE | 503 | The captcha provider could not be reached, so the anonymous lookup did not run. | Retry in a few minutes, or look up with an API token. The evidence bundle verifies offline with OpenSSL. |
X_CASE_ARCHIVED | 409 | The case is archived: it takes no new notification, edit or party. | Reopen it with unarchiveCase; its notifications and evidence were kept. |
X_CASE_IN_FLIGHT | 409 | The case has a notification in progress and cannot be archived yet. | Send or discard that notification (`meta.notificationId`) and retry. |
X_CASE_LOCKED | 409 | The case can no longer be edited: one of its notifications left draft and its data is evidence now. | Create a new case for the corrected data; the sent notification keeps the data it was sent with. |
X_CASE_NOT_FOUND | 404 | No such case in your firm. | Use a `caseId` caseList returns for the same firm. |
X_CASE_RADICADO_INVALID | 422 | The radicado is not a valid 23-digit court number (DANE code, filing year, consecutivo). | Copy the radicado from the auto or from consultaprocesos.ramajudicial.gov.co; dashes and spaces are fine. |
X_CASE_RADICADO_TAKEN | 409 | Your firm already has a case with that radicado. | Use the existing case (its id is in the message) instead of creating another. |
X_CONSTANCIA_NOT_FOUND | 404 | There is no constancia for that notification yet (or not that version). | The constancia is issued when the delivery events arrive; check getNotification and retry later. |
X_CONSTANCIA_NOT_READY | 409 | The notification cannot be sealed yet: it is not sent, or a fact the constancia prints is missing. | Wait for the send to settle and read it again; nothing else is needed. |
X_CORREO_BLANK | 422 | The correo has an empty subject or message. | Write a subject and a message, then retry. |
X_CORREO_MERGE_FIELD | 422 | A correo cannot use fields from a proceso, such as {radicado}: it has no proceso. | Remove the field from the subject or message, or send the notification from the proceso. |
X_COURT_OUTCOME_ATTACHMENT_INVALID | 422 | The `attachmentUploadId` is not a confirmed document of your firm. | Upload the auto with requestUpload, PUT it, call confirmUpload and pass the id it returned. |
X_COURT_OUTCOME_DATE_INVALID | 422 | The decision date (`decidedOn`) is before the send or after today (Bogotá time). | Send `decidedOn` as YYYY-MM-DD between the send day and today. |
X_COURT_OUTCOME_NOTIFICATION_NOT_FOUND | 404 | That notification does not exist in your firm. | Find the id with notificationList and retry with a sent notification of your firm. |
X_COURT_OUTCOME_NOT_SENT | 409 | The notification has not been sent, so no court has ruled on it. | Report the decision once the notification is sent. |
X_COURT_OUTCOME_REASON_REQUIRED | 422 | A rejection or a nulidad request is reported with the court’s reason. | Retry with `reason`: what the auto or providencia says. |
X_CREDITS_INSUFFICIENT | 402 | There are not enough credits to send to every recipient. Nothing was sent. | With `meta.mode` = `free`, write to admin@notificado.co; with `meta.mode` = `paid`, buy credits at /creditos. |
X_CREDITS_LEDGER_TOO_LONG | 413 | Your firm’s credit balance could not be computed in one read. | Write to admin@notificado.co with the `requestId`; do not retry. |
X_CSRF_BLOCKED | 403 | A write authenticated by a session cookie arrived without a same-site `origin`. | From a program, authenticate with a token (`Authorization: Bearer …`) instead of the cookie. |
X_CURSOR_INVALID | 400 | The pagination cursor is not one this API issued, or is no longer valid. | Request the first page without a cursor and follow the cursor each response returns. |
X_DEADLINE_CURSOR_CONFLICT | 422 | The deadlines request carries `cursor` and `after` with different positions. | Send `cursor` alone (the previous page's last row id); `after` is its earlier name. |
X_DOCUMENT_FILENAME_NOT_MAILABLE | 422 | The file's name cannot travel in an email header as written (too long, or characters a mail header cannot carry); `meta.reason` names the limit. Nothing was stored. | Rename the file within the limit in `meta.reason` and upload it again. |
X_DOCUMENT_KEY_INVALID | 422 | The `key` sent to confirmUpload is not a pending upload of your firm. | Pass the `key` requestUpload returned, after the PUT to its `url` succeeded. |
X_DOWNLOAD_CROSS_SITE | 403 | The download was asked for by a page that is not Notificado's own download page. Nothing was recorded. | Open the link from the notification email and use the button on that page. A program calls recordDownload with no `Origin` and no `Sec-Fetch-Site` header. |
X_DRAINING | 503 | The server that received the request is shutting down for a deploy. | Retry the same request in a few seconds; with an `Idempotency-Key` the retry is safe. |
X_EVIDENCE_NOT_FOUND | 404 | No such evidence in your firm. | Use an id getNotification or the evidence reads return. |
X_EVIDENCE_ZIP_FAILED | 409 | The evidence package (zip) for that constancia version could not be built. The PDF constancia is still available. | Write to admin@notificado.co naming the notification and `meta.version`; the team rebuilds it. |
X_EVIDENCE_ZIP_NOT_READY | 409 | The evidence package (zip) for that constancia is still being built. | Retry the download in about 30 seconds. |
X_FORBIDDEN | 403 | Your role does not allow this action, or the `orgId` sent is not your firm’s. | Use the `orgId` whoami returns and a member with the role needed (a lawyer to send, for example). |
X_IDEMPOTENCY_CONFLICT | 409 | That `Idempotency-Key` was already used with a different body, or the first request with it is still running. | Use a fresh key for every distinct request; for a retry of the same one, wait for the first to finish and repeat it unchanged. |
X_IDEMPOTENCY_KEY_INVALID | 400 | The `Idempotency-Key` header was empty or longer than 255 characters. | Send a fresh UUID per request (`crypto.randomUUID()`), or omit the header. |
X_IDEMPOTENCY_REPLAYED_FAILURE | 500 | The first request under that `Idempotency-Key` failed; this answer replays that failure without running anything again. | Read the original code in `meta.code`, fix its cause, and retry with a fresh key. |
X_IMPORT_NOT_FOUND | 404 | That import does not exist in your firm. | Find the id with listImports and retry with one of your firm. |
X_IMPORT_ROW_MOVED | 409 | Another run worked that row first; this run’s changes were rolled back. | Nothing to do: getImport shows what the row became. |
X_IMPORT_UPLOAD_KEY_INVALID | 422 | The `key` is not a pending import upload of your firm. | Call requestImportUpload again, PUT the file and confirm with that exact `key`. |
X_INPUT_INVALID | 400 | A field does not match the operation’s schema; `issues` names each one. | Correct the fields `issues` lists, following the operation’s reference, and retry. |
X_INTERNAL | 500 | A server failure that is not the request’s fault. The details are in our logs, under the `requestId`. | Retry later; if it persists, write to admin@notificado.co with the `requestId`. |
X_INVARIANT_VIOLATED | 422 | A value passed the schema but breaks a data rule (an id that is not a UUID, for example). | Check the ids and values you send: use the ones the API’s reads return. |
X_JURAMENTO_MISMATCH | 422 | The `juramentoText` sent is not the oath the server words for this recipient's email and name, so it is not the oath for this address. Nothing was recorded. | Send the text shown for exactly this email (trimmed, lower-case) and name, or leave `juramentoText` out to swear the server's own wording. |
X_JURAMENTO_REQUIRED | 422 | The Ley 2213 art. 8 oath is missing: that the address is the one the person uses. | A lawyer adds and swears each recipient in the panel; an agent cannot swear. |
X_KYC_CEDULA_INVALID | 422 | The cédula number is not valid: after removing dots, spaces and hyphens it must be 5 to 12 digits. | Type the cédula as it appears on the document; dots are fine. |
X_KYC_CHECK_IN_FLIGHT | 409 | The registry is still being checked with the verification’s current details; a new submission would race that check. | Wait a few minutes (myKyc stops showing `checking`) and submit again only if something must change. |
X_KYC_POSSESSION_CODE_EXPIRED | 410 | The code sent to the SIRNA email expired or ran out of tries. | Ask for a new one with resendPossessionCode or at /cuenta/verificacion, and enter it within 15 minutes. |
X_KYC_POSSESSION_CODE_INVALID | 422 | That is not the code we sent to the SIRNA email. | Enter the 6 digits from the latest email; the answer says how many tries are left. |
X_KYC_POSSESSION_CODE_LIMIT | 429 | Too many codes were requested for the SIRNA email in the last hour. | The latest code sent works until it expires; ask for another with resendPossessionCode after an hour. |
X_KYC_POSSESSION_NO_CHALLENGE | 409 | No code is pending: no verification was submitted, or the email is already confirmed. | Submit the verification at /cuenta/verificacion, or ask for a new code if the last one expired. |
X_KYC_POSSESSION_RESEND_TOO_SOON | 429 | We just sent a code to the SIRNA email. | Check the inbox and the spam folder, or ask again after the seconds in `retry-after`. |
X_KYC_POSSESSION_UNPROVEN | 409 | The code sent to the SIRNA email the lawyer typed is not confirmed yet. | The lawyer enters the code at /cuenta/verificacion; without it there is no approval. |
X_KYC_REQUIRED | 403 | Sending in your own name requires an approved lawyer verification with sends not paused; it is valid in all of the person's firms. | Complete the verification at /cuenta/verificacion (registry lookup and a code to the SIRNA email); meanwhile requestSendApproval asks a verified lawyer of the firm to send. whoami shows `kycApproved`. |
X_KYC_SIRNA_CHANGE_NOT_APPROVED | 409 | Only a lawyer whose verification is approved can change their SIRNA email with changeSirnaEmail. | While the verification is in progress, rejected or revoked, correct the email by submitting the verification again at /cuenta/verificacion. |
X_KYC_SIRNA_EMAIL_INVALID | 422 | The Registro Nacional de Abogados (SIRNA) email contains characters an email message cannot carry (such as accents or ñ). | Type the email exactly as it appears in SIRNA, without accents or ñ. |
X_KYC_SIRNA_EMAIL_UNCHANGED | 409 | That email is already the verified SIRNA address: there is nothing to change. | Send the new address exactly as the SIRNA shows it today. |
X_KYC_SUBMIT_LIMIT | 429 | The verification was submitted too many times in the last 24 hours. | Read with myKyc why it waits: a person on the team reviews it. If something must be corrected, write to support instead of submitting again. |
X_KYC_TARJETA_INVALID | 422 | The tarjeta profesional number is not valid: after removing dots, spaces and hyphens only digits may remain. | Type the number as it appears on the tarjeta profesional. |
X_LAWYER_IDENTITY_DUPLICATE_APPROVED | 409 | That cédula or tarjeta profesional is already approved on another account. | Write to support from /soporte: a person on the team reviews which one is genuine. |
X_LAWYER_IDENTITY_EXISTS | 409 | This account already has a lawyer identity: one account is one person. | Correct the existing one at /cuenta/verificacion instead of creating another. |
X_LAWYER_IDENTITY_NOT_FOUND | 404 | No such lawyer identity. | Use the id myKyc returns; if there is none, submit the verification at /cuenta/verificacion. |
X_LAWYER_IDENTITY_NOT_RESUBMITTABLE | 409 | The verification is approved and valid in all your firms: there is nothing to submit again. | Nothing to do; myKyc shows the status. |
X_LAWYER_IDENTITY_TRANSITION_REFUSED | 409 | Another decision on this verification landed first. | Read the status with myKyc and act on what it is now. |
X_LEGAL_ACCEPTANCE_REQUIRED | 403 | A new version of the terms or the privacy notice is out and the token’s owner has not accepted it. | Sign in with a browser and accept the new version at /cuenta/aceptar-terminos; the same token works again at once. |
X_LINKED_FILES_DISABLED | 409 | Linked files (files too large to attach, delivered by download link) are not available to your firm now. `meta.reasons` says why: not offered yet, or no payment method on file. | For `no_payment_method`, register a payment method at /facturacion and retry. Otherwise attach the files instead (attachDocument, 6 MB in total). linkedFilesAccess answers the reasons. |
X_LINKED_FILE_ALREADY_ATTACHED | 409 | The linked file is already attached to another notification (`meta.notificationId`). One linked file belongs to one notification, because once sent it is that notification's evidence. | If that notification is still a draft, detach it there with detachAttachment and attach it again here. Otherwise upload the file again. |
X_LINKED_FILE_DOWNLOAD_STREAMED | 409 | That download link is of a linked file, which is streamed and never returned by recordDownload. Nothing was recorded. | POST to the link itself (`/r/<recipientToken>/d/<linkToken>`, empty body) and read the response body as the file; a GET only renders the download page. |
X_LINKED_FILE_NAME_INVALID | 422 | The `filename` of a linked file is one we would have to change, or one that misleads: empty, over 255 characters, a control or invisible character, one of / \ : * ? " < > |, a leading or trailing dot or space, or an executable extension inside it. | Rename the file and send its own name, with one real extension, for example "expediente.pdf". |
X_LINKED_FILE_NOT_ATTACHABLE | 409 | The linked file cannot be attached: it is not `clean` (`meta.status`, with `meta.reason` when it was not accepted), or staff blocked it. | While `status` is `scanning`, wait for linkedFileStatus to answer `clean` and retry. A file that was refused, removed or already sent must be uploaded again. |
X_LINKED_FILE_NOT_DISCARDABLE | 409 | The linked file cannot be removed: it is being scanned, or it was sent with a notification and is kept as evidence. | While `status` is `scanning`, wait for linkedFileStatus to change and retry. A sent file cannot be removed. |
X_LINKED_FILE_NOT_FOUND | 404 | No such linked file in your firm. | Use an `id` requestLinkedUpload returned; linkedFileList lists the unsent ones. |
X_LINKED_FILE_NOT_SENDABLE | 409 | The draft lists a linked file that can no longer be sent (`meta.filename`): it is not `clean`, it was blocked, or its bytes are gone. Nothing was charged. | Detach it with detachAttachment (`meta.attachmentId`), upload the file again, attach the new one with attachLinkedFile and send. |
X_LINKED_FILE_QUOTA_EXCEEDED | 409 | Your firm already holds as many unsent linked files as it may (30 files, 10 GB). | Send the notifications that use them, or remove the ones no longer needed with discardLinkedFile. |
X_LINKED_FILE_SIZE_INVALID | 422 | The declared `bytes` of a linked file is not a whole number from 1 to the maximum (`meta.maxBytes`). | Send the file's exact size. A file over the maximum is split before it is uploaded. |
X_LINKED_FILE_TYPE_NOT_ALLOWED | 422 | The file's name does not end in an extension a linked file may have, or the declared type contradicts it. Accepted: pdf, png, jpg, jpeg, tif, tiff, mp3, wav, m4a, ogg, oga, mp4, m4v, mov, webm, mkv, docx, xlsx, pptx, odt and zip. | Send a file named with one of the extensions in `meta.extensions`; pass the browser's File.type as `contentType`, or leave it out. |
X_LINKED_FILE_UPLOAD_MISSING | 409 | confirmLinkedUpload was called before the file reached storage. | PUT the file to the `url` requestLinkedUpload returned, with exactly its `contentType`, wait for the 2xx, then confirm again. |
X_MCP_BODY_TOO_LARGE | 413 | The MCP call is larger than the maximum body size. | Split the call; files are uploaded with requestUpload and a PUT, never inside a tool call. |
X_MCP_RATE_LIMITED | 429 | Too many MCP calls with this token in a short time. | Wait the seconds `Retry-After` names, then retry. |
X_MCP_SCOPE_DENIED | MCP only | The token lacks the scope that tool requires. | Create a token with the needed scope (for example `cases:write`) at /cuenta/api. |
X_MEMORIAL_BLOCKED_BOUNCE | 409 | A recipient bounced: that person was not notified, and the memorial cannot say they were. | Resolve the bounce in the panel (another address, another channel) before generating the memorial. |
X_MEMORIAL_CONSTANCIA_PENDING | 409 | Delivery happened, but the constancia the memorial cites is not issued yet. | Retry in a few seconds, once getNotification shows the constancia. |
X_MEMORIAL_NOTIFICATION_NOT_FOUND | 404 | No such notification in your firm. | Use a `notificationId` notificationList returns for the same firm. |
X_MEMORIAL_NOT_DELIVERED | 409 | The notification is not sent yet, or a recipient’s mail server has not accepted the message yet. | Wait for the delivery events (getNotification), then generate the memorial. |
X_MEMORIAL_NOT_FOUND | 404 | No such memorial in your firm, or its generation has not finished. | List memoriales with notificationMemorials and use an id it returns; a new one appears within seconds. |
X_MEMORIAL_TERM_PENDING | 409 | Delivery happened, but a recipient’s term has not been computed yet. | Retry in a few seconds; listDeadlines shows when it is ready. |
X_METHOD_NOT_ALLOWED | 405 | The path exists but does not accept that HTTP method. | Actions are called with POST and queries with GET; check the operation’s reference. |
X_NOTIFICATION_ATTACHMENTS_TOO_MANY | 422 | The notification would go over the maximum number of attachments. | Merge the annexes into one PDF, or send the rest in a second notification. |
X_NOTIFICATION_ATTACHMENT_NOT_FOUND | 404 | That attachment does not belong to that notification of your firm. | Use an id from `attachments` in getNotification. |
X_NOTIFICATION_CASELESS | 409 | This action needs a notification sent from a proceso; a correo sin proceso has no juzgado. | Use a notification created on a proceso (createNotification). |
X_NOTIFICATION_DISCARD_REFUSED | 409 | That draft cannot be discarded: it has evidence or waits for an approval or a confirmation. | Read `meta.reason`; if it waits for a confirmation or an approval, let it expire or be decided first. |
X_NOTIFICATION_DOCUMENT_NOT_FOUND | 404 | The document is not an upload of your firm, or not of the kind needed. | Upload the file first (requestUpload, PUT, confirmUpload) and pass the id confirmUpload returns. |
X_NOTIFICATION_EVIDENCE_TOO_LARGE | 413 | With those attachments and that many recipients, the evidence package would exceed the size that can be kept and delivered. Nothing was charged. | Keep recipients per notification at `meta.maxRecipients` or fewer (create another notification for the rest), or shrink the attachments. |
X_NOTIFICATION_IS_CORREO | 409 | This draft is a correo sin proceso; updateDraft edits art. 8 drafts. | Use updateCorreo with the subject and message. |
X_NOTIFICATION_NOT_CORREO | 409 | This draft is a notification on a proceso; updateCorreo edits only a correo sin proceso. | Use updateDraft for an art. 8 draft. |
X_NOTIFICATION_NOT_DRAFT | 409 | The notification is no longer a draft: its content was frozen as evidence. | Create a new draft with createNotification instead of editing the sent notification. |
X_NOTIFICATION_NOT_FOUND | 404 | No such notification in your firm. | Use an id notificationList returns for the same firm. |
X_NOTIFICATION_NOT_MAILABLE | 422 | One of the message fields (`meta.field`) cannot be put into an email as written. Nothing was charged. | Correct the field named in `meta.field` (for example a name or address with unsupported characters) and send again. |
X_NOTIFICATION_NOT_SCHEDULED | 409 | The notification is not scheduled: it already left, its schedule was cancelled, or it was never scheduled. | Read its status with getNotification. A draft can be sent or scheduled again with sendNotification. |
X_NOTIFICATION_NO_ATTACHMENTS | 422 | The notification has no attachment: an art. 8 notification sends the providencia itself. | Attach the providencia with attachDocument, then send. |
X_NOTIFICATION_NO_RECIPIENTS | 422 | The notification has no recipient. | A lawyer adds and swears at least one recipient in the panel; then send. |
X_NOTIFICATION_RECIPIENT_NOT_FOUND | 404 | That recipient does not belong to that notification of your firm. | Use an id from `recipients` in getNotification. |
X_NOTIFICATION_SCHEDULED | 409 | The notification is scheduled to be sent: what was confirmed is what will leave, and its content cannot change while it waits. | Cancel the schedule with cancelScheduledSend; the notification is a draft again that you can edit and send or schedule again. |
X_NOTIFICATION_TRANSITION_REFUSED | 409 | The notification cannot move to that state from its current one, or its state changed meanwhile. | Read it again with getNotification and act on its current state. |
X_ORG_INVITE_SECOND_FACTOR_REQUIRED | 403 | The session proved the password but not the authenticator code; the invitation was not used. | Finish signing in with the code and open the invitation link again. |
X_ORG_OWNER_CHANGE_UNPROVEN | 409 | The change affects an owner of the firm and lacks the identity confirmation it requires, or the roles changed since the page loaded. | Reload the members page and retry with the authenticator code or the password. |
X_ORG_SUSPENDED | 403 | Your firm’s sending is suspended, by the Notificado team or automatically after recipient complaints. | Write from the account owner’s address to the contact the message names to ask for a review. |
X_OVERLOADED | 503 | The server is handling more requests than it admits right now. | Retry after the seconds in `Retry-After`, backing off. |
X_PAGE_LIMIT_INVALID | 422 | The requested page size is outside the range this list accepts. | Ask for at most the limit the Limits guide gives, and follow the cursor to read the next page. |
X_PARTY_ADDRESS_NOT_FOUND | 404 | That saved address does not exist in your firm or was removed. | Take the id from partyAddresses of the same case. |
X_PARTY_ADDRESS_PROVENANCE | 422 | The saved address has no valid provenance. | Send exactly one of `evidenceDocumentIds` (your firm’s proofs) or `overrideReason`. |
X_PARTY_NOT_FOUND | 404 | That party does not exist in your firm. | Take the id from `parties` in getCase of the same case. |
X_PDF_INFLATE_LIMIT | 422 | The uploaded PDF is a decompression bomb: its object streams inflate past 64 MiB at 100:1 or more. | Print it to a new PDF (or `gs -o new.pdf -sDEVICE=pdfwrite file.pdf`) and upload that file. |
X_PROVENANCE_REQUIRED | 422 | Proof of how the address was obtained is missing, or a written reason why there is none. | State where the address came from when the recipient is added in the panel. |
X_RATE_LIMITED | 429 | You went over this operation’s request limit for your user or token. | Wait the seconds `Retry-After` names, then retry. |
X_RECIPIENT_ACK_BY_SENDER | 403 | The acknowledgement of receipt came from a signed-in member of the firm that sent the notification; only the recipient may acknowledge it. | Sign out of Notificado and let the recipient open their own link; the sender follows the status in the notification detail. |
X_ROUTE_NOT_FOUND | 404 | No operation lives at that path. | Check the path and the `/v1` prefix in the API reference. |
X_SCHEDULED_DRAFT_CHANGED | 409 | At the scheduled time the notification was no longer what had been confirmed: a file or a recipient changed. | Review the draft with getNotification and confirm it again with sendNotification. |
X_SCHEDULED_SENDER_NOT_MEMBER | 403 | The person who scheduled the send is no longer a lawyer or owner of the account, so the send did not leave under their oath. | Another lawyer or owner of the account sends the draft with sendNotification, under their own oath for each address. |
X_SCHEDULED_SEND_NOT_SCHEDULER | 403 | Only the lawyer who scheduled the send can send it before its scheduled time: the oath of that send is theirs. | Cancel the schedule with cancelScheduledSend and send the notification yourself, or let it leave at its time. |
X_SCHEDULE_CLOSURES_TOO_MANY | 422 | More court closures are recorded between today and the next opening than the record of the schedule can state. | Send the notification now with when: "now", or remove the duplicated closures of those days and schedule it again. |
X_SENDER_LIMIT_REACHED | 429 | This send would take your firm past its hourly or daily recipient limit. | Send later (the window rolls), to fewer recipients, or ask the contact in the message for a higher limit. |
X_SEND_ALREADY_CONFIRMED | 409 | That send was already confirmed and the notification went out once; it is not sent again. | Nothing to do: follow the notification with getNotification. |
X_SEND_APPROVAL_NO_DECIDER | 409 | Nobody in the firm besides you is a verified lawyer or owner who could approve the send, so no approval request was filed. Nothing was sent and the draft is unchanged. meta.stop says why: paused, verify or invite. | paused: your sends are paused by the weekly registry check; see /cuenta/verificacion and write to support. verify: finish the verification at /cuenta/verificacion, then send the draft yourself. invite: ask the firm owner to verify or to invite a verified lawyer at /cuenta/miembros, then request again. |
X_SEND_CONFIRMATION_EXPIRED | 410 | Nobody confirmed the send within 24 hours; nothing was sent. | Call sendNotification again for a new link, or send the draft from the panel. |
X_SEND_CONFIRMATION_NOT_FOUND | 404 | No such send confirmation in your firm. | Open the `confirmUrl` the agent handed over while signed in to the same firm, or send from the panel. |
X_SEND_CONFIRMATION_STALE | 409 | The draft changed after the confirmation was requested; what would be confirmed is not what the agent asked to send. | Review the draft and send it from the panel, or call sendNotification again. |
X_SEND_CONFIRMATION_TOKEN_REVOKED | 410 | The token that requested this send was revoked; its confirmation can no longer be used. | If the send is still right, review the draft and send it from the panel. |
X_SEND_SCHEDULING_OFF | 409 | Scheduled sends are not enabled on this service. | Send the notification now with when: "now", or leave it a draft and send it later. |
X_SEND_WHEN_REQUIRED | 422 | The send was confirmed outside the reference hours and the next opening is more than 96 hours away: the service does not hold it by itself. | Repeat sendNotification with when: "now" to send it at once, or when: "next_business_open" to schedule it. |
X_STORAGE_TOO_LARGE | 413 | The file sent in the PUT is larger than the upload grant allows (20 MB). | Compress or split the document and request a new upload with requestUpload. |
X_STORAGE_TYPE_REJECTED | 415 | The PUT file is not a PDF, PNG or JPEG, or does not match the `contentType` requested. | Upload a PDF, PNG or JPEG with a `Content-Type` header exactly equal to requestUpload’s `contentType`. |
X_STORAGE_URL_EXPIRED | 410 | The upload URL expired (`expiresAt` has passed). | Request a new upload with requestUpload and a fresh `Idempotency-Key`, and PUT right away. |
X_STORAGE_URL_INVALID | 403 | The upload URL was altered, or this server did not sign it. | Use the `url` requestUpload returned verbatim, without changing its query. |
X_SUBSCRIPTION_OVERAGE_CAP | 402 | Your plan’s extra sends for this cycle reached their cap. | Buy credits at /creditos or wait for the next cycle. |
X_SWITCH_CHANNEL_LINKED_FILE | 409 | The notification delivered a linked file, and a linked file is never attached again to a re-issued notification. Nothing was copied or charged. | Send a new notification: upload the file again (requestLinkedUpload, PUT, confirmLinkedUpload), attach it with attachLinkedFile and call sendNotification. |
X_TEMPLATE_ARCHIVED | 409 | The template is archived. | Restore it at /cuenta/plantillas or pick another with listMessageTemplates. |
X_TEMPLATE_FIELD_UNKNOWN | 422 | The template uses a field no case fills. | Use only the fields in `meta` or write the text itself. |
X_TEMPLATE_NOT_FOUND | 404 | That template does not exist in your firm. | Take the id from listMessageTemplates. |
X_TENANCY_ACTOR_ORG_REQUIRED | 403 | The call is not tied to any firm. | Use a token issued by a firm at /cuenta/api, or sign in to a firm. |
X_TERM_DAYS_INVALID | 422 | The term is not a whole number of business days within the allowed range. | State the term in días hábiles as the providencia says it (20 for a traslado, for example). |
X_TIMEOUT | 504 | The operation took longer than allowed and was cut off. | Retry with the same `Idempotency-Key`: if the first attempt completed, you get its result without a repeat. |
X_UNAUTHENTICATED | 401 | The request carries no valid credentials: the token is missing, revoked or expired. | Send `Authorization: Bearer <token>` with a live token from /cuenta/api. |
X_WEBHOOK_ENDPOINT_LIMIT | 409 | Your firm reached the maximum number of webhook endpoints. | Delete one you no longer use with deleteWebhookEndpoint, or subscribe an existing one to more events. |
X_WEBHOOK_ENDPOINT_NOT_FOUND | 404 | That webhook endpoint does not exist in your firm or was deleted. | Take the id from listWebhookEndpoints. |
X_WEBHOOK_EVENT_TYPE_UNKNOWN | 422 | One of the event types does not exist. | Subscribe only to the types `meta.known` lists. |
X_WEBHOOK_URL_INVALID | 422 | The webhook URL is refused: it is not an absolute URL of at most 2000 characters, or it carries a user name or password. | Call createWebhookEndpoint with an absolute https URL of at most 2000 characters and no credentials in it. |
X_WEBHOOK_URL_NOT_HTTPS | 422 | The webhook URL is refused: it is not https. | Call createWebhookEndpoint with a public https URL on port 443. |
X_WEBHOOK_URL_PORT | 422 | The webhook URL is refused: it names a port other than 443, the only one that leaves our network. | Call createWebhookEndpoint with a public https URL on port 443, without a port in it. |
X_WEBHOOK_URL_PRIVATE | 422 | The webhook URL is refused: its host only resolves inside a private network, is Notificado itself, or resolves to a private, loopback, link-local, CGNAT or otherwise non-public address. | Call createWebhookEndpoint with a public https URL on port 443 whose host resolves only to public addresses. |
X_WEBHOOK_URL_UNRESOLVABLE | 422 | The webhook URL is refused: its host does not resolve in public DNS. | Check the host name, publish its DNS record, and call createWebhookEndpoint with a public https URL on port 443. |