REST integration — messages
Not yet checked on the product
This chapter was written from the product's source code and has not yet been checked by a person on a running Cogneris. If what you see on screen differs, the screen is right — please tell your Cogneris contact so the chapter can be corrected.
Every message the REST integration can show in the workflow editor, with its cause and the fix. Where a message carries a name or a number, it is shown here as ….
| Content status | From source; not observed (workflow-fe f88c5c1, workflow-be 6703373, 2026-10-22) |
Where they appear. Problems of the settings are listed above the tabs as you edit, whatever tab is open. Mapping issues appear in the form of the rule they belong to, and the mapping tab counts them in Issues to fix: …. The other messages appear next to the field or button concerned. The editor does not block saving while problems are listed; publishing is refused by the service for the same reasons (see Refused by the service).
Messages in the editor
| Message | Where | Cause | What to do |
|---|---|---|---|
| Choose a connection. | Problems | No Connection selected | Select a connection in Request. |
| Could not load the connections. | Request | The list of connections did not load | Reload the editor; if it persists, contact support. |
| Fill in the path. | Problems | Path is empty | Type the path, starting with /. |
| The path must be relative to the connection: no scheme or host. | Problems | Path starts with a scheme such as https: or with // | Keep only the path; the host belongs to the connection's Base URL. |
| The path parameter … has no rule. | Problems | The path has a name in curly braces with no entry under Path parameters | Edit the path again so the entry is created, then give it a source. |
| The path parameter … needs a source. | Problems | The entry has no Source and no first transform that produces a value | Pick a Source, or start its transforms with constant, concat or coalesce. |
| Every query parameter needs a name. | Problems | A query parameter has an empty Name | Name it, or Remove it. |
| The query parameter … needs a source or a fixed value. | Problems | Neither Source, a value-producing first transform, nor Fixed value | Give it one of them. |
| The query parameter … looks like a credential: it cannot be set in the phase and is not saved. Use a connection of type API key in the query. | Problems | The name is one of the refused credential names (see Request) | Remove it; create an API key connection with API key location Query string. |
| Every header needs a name. | Problems | A header has an empty Header name | Name it, or Remove it. |
| The header … cannot be set in the phase: authentication and secrets belong to the connection. | Problems | The name is Authorization, Proxy-Authorization, Cookie, X-API-Key, Api-Key or Idempotency-Key | Remove it; the connection supplies authentication, and the Idempotency-Key option sends that header. |
| The timeout must be between … and … seconds. | Problems | Timeout (seconds) outside 1–120 | Enter a whole number in range, not above the connection's timeout. |
| The timeout cannot be longer than the connection's (… seconds). | Problems | Timeout (seconds) is above the selected connection's timeout | Lower it, or raise the connection's Timeout (seconds, 1 to 120). |
| Retries must be between … and …. | Problems | Retries outside 0–10 | Enter a whole number in range. |
| The wait between retries must be between … and … seconds. | Problems | Wait between retries (seconds) outside 1–600 | Enter a whole number in range. |
| Enter at least one success status code. | Problems | Success status codes is empty or has no number | Enter at least one 2xx code, for example 200. |
| … is not a success status code: success codes must be between 200 and 299. | Problems | A success code outside 200–299 | Keep only 2xx codes; use Not-found status codes (4xx) in Result for a not-found status. |
| … is not a 4xx status code: not-found codes must be between 400 and 499. | Problems | A code outside 400–499 in Not-found status codes (4xx) | Correct it, or empty the field. |
| Rule … needs a field in the response. | Problems | A rule of Rules on the response body has no Field in the response | Fill it, or remove the rule. |
| Rule … needs a value for its operator. | Problems | The operator compares with a value and Value is empty | Fill Value, or choose exists or isempty. |
| At most … result rules are allowed. | Problems | More than 20 rules on the response body | Remove rules. |
| Check … needs a field in the request body. | Problems | A check before the call has no Field in the request body | Fill it, or remove the check. |
| Check … needs a value for its operator. | Problems | Same as for result rules, on a check before the call | Fill Value. |
| The result data of check … must be a JSON object. | Problems, and under the check | Result data (JSON object, optional) is not valid JSON, or is not an object | Write an object, or empty the field. Until fixed, the data is not saved. |
| At most … checks before the call are allowed. | Problems | More than 20 checks | Remove checks. |
| The document type must start with a lowercase letter and use only lowercase letters, digits and underscores (2 to 64 characters). | Problems | Document type is empty or malformed while Publish the result is on | Use a name such as customer_lookup, or turn publication off. |
| The display name can have at most … characters. | Problems | Display name (optional) longer than 120 characters | Shorten it. |
| Choose at least one result to publish. | Problems | No outcome checked under Publish when the result is | Check at least Success. |
| The proof title can have at most … characters. | Problems | Title (optional) longer than 120 characters | Shorten it. |
| The proof field "…" is not a valid path (letters, digits, hyphen and underscore, separated by dots) or its label is too long. | Problems | A line of Fields to print (optional) has a bad path or a label over 80 characters | Use path or path | label, for example vies.name | Name. |
| The proof can print at most … fields. | Problems | More than 30 lines in Fields to print (optional) | Remove lines. |
| The file name uses characters or placeholders that are not allowed. | Problems | File name (optional) has characters other than letters, digits, ., -, _, an unknown placeholder, or more than 120 characters | Use only those characters and the placeholders listed under the field. |
| Unknown transform "…". | Rule form | The configuration names a transform type that does not exist | Remove the transform. |
| The rule has no target path. | Rule form | Target path is empty | Type the target, or remove the rule. |
| Target "…" does not exist in the schema. | Rule form | The target is not a field of the Request schema | Correct the target, or add the field to the schema. |
| A source is required unless the first transform is constant, concat or coalesce. | Rule form | No Source, and the first transform does not produce a value | Pick a source, or start with one of those transforms. |
| date_format needs both the input and output formats. | Rule form | An empty format in a date_format | Fill both, or use iso. |
| lookup needs at least one entry in the table. | Rule form | The lookup table is empty | Add pair. |
| The lookup fallback is not valid. | Rule form | A stored fallback that is none of the four choices | Choose a fallback in When the value is not in the table. |
| concat needs at least one source path. | Rule form | Source paths (one per line) is empty in a concat | Add paths. |
| coalesce needs at least one source path. | Rule form | Same, in a coalesce | Add paths. |
| to_boolean needs at least one true value and one false value. | Rule form | A list of to_boolean is empty | Fill both lists. |
| The decimal separator must be "." or ",". | Rule form | A stored number_format with another separator | Choose . or ,. |
| regex_extract needs a pattern of 1 to … characters. | Rule form | The expression is empty or longer than 256 characters | Write an expression up to 256 characters. |
| regex_extract: the group must be a whole number from 0 up to the number of groups in the pattern. | Rule form | Capture group (0 = whole match) is negative, not whole, or larger than the number of groups | Use 0 for the whole match, or the number of a group of the expression. |
| Required field "…" has no rule. | Rule list | A field the Request schema requires has no rule | Map it, or remove it from required in the schema. |
| Arrays can be nested up to … levels. | Rule form | Item rules nested more than 3 levels deep | Flatten the structure. |
| Item rules only apply to array targets (ending in []). | Rule form | Item rules on a target that is not a list | Make the target end in [], or remove the item rules. |
| Source "…" was not found in the sample. | Rule form (warning) | The source is not a path of the Input example | Check the spelling. If the example is just incomplete, the rule still works. |
| Source "…" is not valid: use $form.…, $process.…, $doc.….…, $doc.…[].… or $run.id, $run.workflowId, $run.tenantId. | Rule form | A source starts with $ but is not a well-formed reserved source: unknown root, missing key, $doc without type or field, unknown $run key | Correct it, for example $form.nif. |
| Source "…" is not valid here: a response rule can only read what was sent, with $request.…. | Rule form | A response rule reads $form, $process, $doc, $run or another $ root | Read the answer, or $request. + a field of what was sent. |
| Source "…" reads the run ($form, $process, $doc, $run) and can only be used in top-level rules, not in item rules. | Rule form | A reserved source inside item rules | Map it in a top-level rule instead. |
| Invalid JSON: … | Schemas | The schema, the example to infer from or the Input example (JSON) is not valid JSON | Fix the JSON; the message gives the parser's explanation. |
| Not a valid schema: describe an object (type "object") or an array (type "array"). | Schemas | Valid JSON that does not describe an object or a list | Paste a schema whose root is an object or an array. |
| Save the workflow before loading an example from a run. | Schemas | The workflow was never saved | Save it. |
| No recent run reached this phase yet. | Schemas | No process completed the previous phase yet | Run a process, or type an example. |
| Loading from a run is not available in this environment yet. | Schemas | The service does not offer it here | Type an example. |
| Could not load the recent runs. | Schemas | Any other failure | Try again. |
| Choose a connection and a valid path before testing. | Test | No connection, empty or absolute path, or a refused header or query parameter | Fix those problems. |
| There is no input example: mappings will read an empty input. | Test | Input example (JSON) is empty | Add an example in Schemas for a meaningful test. |
| Too many tests in a short time. Wait a minute and try again. | Test | More than 10 tests per minute in your company | Wait. |
| The test call is not available in this environment yet. | Test | The service does not offer the test here | — |
| The test could not be run. Check the settings and try again. | Test | The service refused the settings, or could not make the call | See Refused by the service. |
| Fill in this parameter. | Preset form | A required preset parameter is empty | Fill it. |
| Use a two-letter country code in capitals, for example PT. | Preset form | A country parameter is not two letters | Type two letters. |
| This source is not valid: use $form.…, $process.… or $doc.….…. | Preset form | A source parameter starts with $ but is malformed | Correct it, for example $form.nif. |
| This connector needs a connection that does not exist yet in your organization, and only an administrator can create it. Ask an administrator to add this preset once; after that you can use it. | Preset form | First use of the preset in your company, by someone who is not an administrator | Ask an administrator to add the preset once. |
| The value of "…" was refused. Check it and try again. | Preset form | The service refused that parameter — for example Requester country without Requester VAT number, or the reverse | Correct it. |
| One of the parameters was refused. Check them and try again. | Preset form | The service refused a parameter without naming it | Check every parameter. |
| This preset is no longer available. Reload the page to update the list. | Preset form | The preset was removed from the catalog | Reload the page. |
| Could not prepare the connector. Try again in a moment. | Preset form | Any other failure | Try again. |
| The preset catalog is not available right now, so its parameters cannot be reopened. The node keeps working as configured. | Preset banner | The catalog did not load, or no longer has this preset | Try later; the phase still runs. |
| …: fill in the parameters to finish this connector. | Preset banner | The phase came from a workflow template and its preset parameters were never applied | Preset parameters › Apply parameters. |
The messages of the Connections screen are in Overview and VIES tutorial.
Refused by the service
When you publish, and when you test, the service checks the configuration again. The editor shows the service's message, which names the phase and the field. These are the checks the editor cannot make while you edit:
| Rule the editor does not check | What to do |
|---|---|
| The connection must exist in your company | Select another connection. A phase that came from a workflow template names the connection it expects; create a connection with that name and select it. |
| A header cannot be the one that carries the connection's API key | Remove the header. |
| Document type cannot be the name of one of your extraction templates | Choose another name. |
Schemas must be draft-07 or 2020-12, within 256 KB, 64 levels and 20000 nodes, without patternProperties | Simplify the schema. |
A transform's parameters must be usable: a regular expression the service can compile, a date pattern and a time zone it recognises, no value in both lists of to_boolean | Correct the transform. |
| At most 50 path or query parameters, 50 headers, 500 rules per mapping, 20 REST integration phases per workflow | Reduce them. |
Errors at run time
A failure during a process is not shown in the editor: it is written in the phase's output, under restCall. node id .error, and the process continues on Error (or fails, when Error is not connected). The Test tab shows the same output.
error.kind | Meaning | Retried? |
|---|---|---|
transient | 5xx, 408 or 429; no answer within the timeout; host not found; connection failure; the credentials could not be decrypted at that moment; a Transient (retry) rule matched | Yes, up to Retries |
permanent | Any other 3xx or 4xx; a body larger than 5 MB; an invalid configuration; the OAuth2 token request refused; a Permanent (error) rule matched | No |
request_schema | The request could not be built: a mapping or a transform failed, a path parameter had no value, or the body did not match the Request schema | No |
response_schema | A success body that is not JSON, does not match the Response schema, or on which the Response mapping failed | No |
connection | No connection configured, the connection was deleted, or its stored credentials are unreadable — enter them again in Connections | No |
ssrf | The request would leave the connection's host or base path, or the host resolves to a private address | No |
not_found | A not-found result while Not found is not connected | No |
preflight | A check before the call decided Permanent (error) | No |
error.message explains the cause; for a failed transform it names the rule, the transform and the value. error.bodyExcerpt holds up to 2 KB of the destination's answer, without the connection's secrets.
Related
- REST integration
- Request · Schemas and mapping · Result, Test and Publication
- Overview and VIES tutorial
Last reviewed 2026-10-22 · Version 1.0.0 · Owner: product-documentation