Errors and troubleshooting
This page is the reference for the errors of the TOM External API: the shape of the error body, how to read the HTTP status together with the error code, the catalogue of codes and what to do about each one.
1. The error body
Every error returns a JSON object with the media type application/problem+json:
{
"status": "Bad Request",
"statusCode": 400,
"errorCode": "AE_ERR_412",
"errorMessage": "Axis '1' in dimension 'ROWS' is invalid: variables[0] (id 'SEX'): field 'subtype' is required for VAR"
}
| Field | Meaning |
|---|---|
status | The reason phrase of the HTTP status, for example Bad Request. |
statusCode | The HTTP status of the response, repeated in the body, as a number. |
errorCode | The stable, machine-readable error code. Branch on this value, together with the HTTP status and the endpoint. |
errorMessage | A human-readable explanation, usually naming the offending field and where it is. It can be translated into the language of the user and can change at any time: never parse it. |
errorCode is an open set: besides the codes of this API, the platform behind it passes its own codes through, so do not reject a code you do not know. Handle it with the HTTP status.
2. Families of codes
E<status>are generic HTTP errors:E400(malformed JSON),E401(missing API key),E404(unknown route),E405,E406andE415(section 4.1) and so on.AE_ERR_nnncome from this API. The number afterAE_ERR_is not an HTTP status. Some codes mean different things on different endpoint families, for exampleAE_ERR_411andAE_ERR_412(section 4.2), so always read the code together with the endpoint that returned it.GEN_ERR_500is an unexpected failure.VAL_ERR_001is a failed constraint of the request body.- Any other prefix (
WS_ERR_*,RC_ERR_*,TR_ERR_*,TGL_ERR_*,JOB_*, ...) is passed through from the platform, usually with HTTP400.
3. How the HTTP statuses are used
| Status | What it means here |
|---|---|
400 | An invalid request, and also the business errors of the platform: a workspace that does not exist (WS_ERR_101), a survey that is disabled (SO_ERR_201), a variable that is unknown, a statistic that does not apply. Look at errorCode. |
401 | The API key header is missing (E401), or, on calculation endpoints, the survey is not in the user's profile (SO_ERR_203). A 401 does not always mean a bad key. |
403 | A module that is not enabled (AE_ERR_408, also for a key that does not identify a TOM user on the operations that need a module), a survey you cannot use on the variables, carriers and tree endpoints (AE_ERR_415), a target you cannot see (AE_ERR_407), or a workspace shared with you when you try to delete it or one of its elements (AE_ERR_418). |
404 | An unknown route (E404), a target or element that does not exist (AE_ERR_406, AE_ERR_404, AE_ERR_419), a workspace that does not exist when you delete (AE_ERR_417) or a job that does not exist (JOB_NOT_FOUND). |
405, 406, 415 | The request does not match the operation at the HTTP level: a method the path does not accept (E405), an Accept header without the media type the operation returns (E406), or a body that is not sent as application/json (E415). |
409, 410 | The result of an optimization is not available: not finished, failed or cancelled (409), or expired (410). |
422 | A TGL expression that cannot be parsed (TGL_INVALID): when you create or update a target, and in the filterTgl of a calculation. |
429 | Too many queued background jobs (JOB_USER_LIMIT_REACHED). |
500 | An unexpected failure (GEN_ERR_500), including a calculation that exceeds the time limit and a workspaceId that does not exist in the get-workspace operation. |
4. Catalogue of codes
4.1. Generic codes
| Code | Status | Meaning | What to do |
|---|---|---|---|
E400 | 400 | The body is not valid JSON, or cannot be read. | Fix the JSON and the Content-Type header. |
E401 | 401 | The X-API-Key header is missing. | Send the header on every request. |
GEN_ERR_500 | 500 | An unexpected failure, including a calculation that takes longer than about two minutes and a workspaceId that does not exist in the get-workspace operation. | Retry with a smaller request. If it persists, contact support (section 8). |
E500 | 500 | Another unexpected failure. | Handle it like GEN_ERR_500. |
VAL_ERR_001 | 400 | A constraint of the request body failed: a required text is missing or empty, or a text is too long, for example the name of a workspace, the label or tgl of a target, or a title of a saved evaluation longer than 100 characters. The message usually does not say which field. | Check the required fields and the maximum lengths of the operation. |
The HTTP layer can answer these codes on any operation, before the operation runs, with the same error body (application/problem+json):
| Code | Status | When | What to do |
|---|---|---|---|
E404 | 404 | The path does not match any operation. | Check the URL. |
E405 | 405 | The path exists, but not with this method, for example a GET or a DELETE on /api/v2/table/{surveyCode}. | Use the method of the operation. |
E406 | 406 | The Accept header does not include the media type that the operation returns: application/json, or text/html for POST /api/v2/table/{surveyCode}/html. For example, Accept: text/csv. | Send Accept: application/json, or Accept: text/html for the HTML table. |
E415 | 415 | The Content-Type of a POST or PUT with a body is not application/json, for example text/plain or a form. | Send Content-Type: application/json. |
4.2. Codes of this API (AE_ERR_*)
A code can have several rows: each row is a different meaning, and Where names the operations that give it. AE_ERR_411 and AE_ERR_412 change meaning with the family of the endpoint:
| Code | Tables (table, HTML table, Reach) | Media planning (ranking, evaluation, saving an evaluation, response curve) | Tree queries | Optimization |
|---|---|---|---|---|
AE_ERR_411 | 400: an unknown field in a strict object of the request. | Not used. | Not used. | 400: target or targetBase with both or neither of id and filterTgl. An unknown field is AE_ERR_400. |
AE_ERR_412 | 400: a required value is missing. | 400: an item of a list is null or has no id. | 400: treeType has a null item. | 409: the result was requested before the job finished. |
| Code | Status | Meaning | Where |
|---|---|---|---|
AE_ERR_400 | 400 | An invalid value of a field: a negative decimals; an extraParams switch with an invalid value; a response curve with no carriers, a carrier without insertions, memorizationCoefficient together with weightings or outside 0 to 100, intervals that are not positive and strictly ascending, more planLabels than plans or more weightings than ranges; a tree query whose method has no type; a survey tree query that sends ALL with nodesId or nodes. | Table, HTML table, Reach, response curve, tree queries |
AE_ERR_400 | 400 | weeks or weight of the table with a tableType other than TABULATION or REACH_TABLE, a week or a weighting the survey does not have, or a week sent twice; targetMedia or diaryFilters with a tableType that is not Reach. The message names the field or the value. | Table, HTML table, Reach |
AE_ERR_400 | 400 | axis is DIFFERENCES and tableType is not TREND. | Statistics |
AE_ERR_400 | 400 | A body value of the wrong JSON type, such as a number where a list goes or a string where a boolean goes, or a JSON array where an object is expected. The message names the field by its path, for example dimensions[1].axis[0].sources[0].selected. | Every operation with a body |
AE_ERR_400 | 400 | An unknown field in the optimization request, in target, in targetBase, in a candidate carrier or in an objective. The message names the field and the object that contains it. | Submit an optimization |
AE_ERR_401 | 400 | An invalid value of an enumerated field of the body, or of the tableType, type or axis query parameter. In Reach, the tableType is required and only its three modes, REACH_TABLE, REACH_DUPLICATION and REACH_TREND, are valid: a missing one is also AE_ERR_401. The message names the field and lists the valid values, which are case-sensitive. | Statistics, get a workspace, tree queries, table, HTML table, Reach, optimization |
AE_ERR_402 | 400 | A statistic that does not apply to this kind of calculation. | Ranking, evaluation |
AE_ERR_402 | 400 | In a REACH_TREND, a statistic outside the catalog of its axis: in STATISTICS, the statistics of a REACH_TABLE; in DIFFERENCES, the differences of a trend. The message names the ids. | Table, HTML table, Reach |
AE_ERR_403 | 400 | A statistic that is not available for the type of the survey. | Ranking, evaluation |
AE_ERR_404 | 400 | More than one selected item or category in an axis that is not in PLANES, or more than one selected survey wave in a SOURCES axis in PLANES. | Table, Reach |
AE_ERR_404 | 404 | The element does not exist in the workspace. | Get a workspace element |
AE_ERR_405 | 400 | target or targetBase has neither a non-blank id nor a non-blank filterTgl. The message names the field. | Table, HTML table, Reach, ranking, evaluation, saving an evaluation, response curve |
AE_ERR_406 | 404 | The saved target id does not exist in any workspace visible to the user. | Ranking, evaluation, saving an evaluation, response curve, get a workspace element |
AE_ERR_407 | 403 | The target exists but the user cannot see it. | Same as above |
AE_ERR_408 | 403 | The application module the operation needs is not enabled for the user, or the user's modules could not be resolved, which is also the answer to a key that does not identify a TOM user. Reach is the module of every Reach table type, REACH_TREND included. | Statistics, table, HTML table, Reach, Reach capabilities, ranking, evaluation, saving an evaluation, response curve, optimization |
AE_ERR_409 | 400 | An axis without axisType, or with an unknown value. | Table, HTML table, Reach |
AE_ERR_409 | 400 | An optimization without objectives. | Submit an optimization |
AE_ERR_410 | 400 | An axis type that is valid only in responses (MEDIA, MEDIA_PLANS). | Table, HTML table, Reach |
AE_ERR_409, AE_ERR_410 | 400 | A SOURCES or DIFFERENCES axis in a table that is not a TREND or a REACH_TREND, or the CARRIERS axis of a REACH_TREND in PLANES. | Table, HTML table, Reach |
AE_ERR_410 | 400 | An optimization without candidate carriers. | Submit an optimization |
AE_ERR_411 | 400 | An unknown field in an object of the table model that does not accept it: request, its weight, dimension, axis, split category, survey wave of a SOURCES axis or its weight. | Table, HTML table, Reach |
AE_ERR_411 | 400 | The target or the targetBase of an optimization has both the saved target id and an inline expression (filterTgl), or neither. The message names the field. | Submit an optimization |
AE_ERR_412 | 400 | A required field of an axis is missing: the list of the axis (variables, statistics, categories...), parentId, or the subtype, id or filterTgl of a variable. Also a weight without id, in the table or in a survey wave, and a REACH_TREND without its SOURCES, DIFFERENCES or CARRIERS axis. | Table, HTML table, Reach |
AE_ERR_412 | 400 | An item of carriers or statistics is null or has no id, or, in a response curve, intervals or weightings has a null item. The message gives its position. | Ranking, evaluation, saving an evaluation, response curve |
AE_ERR_412 | 400 | treeType has a null item. The message gives its position. | Tree queries |
AE_ERR_412 | 409 | The optimization has not finished yet. | Get the result of an optimization |
AE_ERR_413 | 400 | No computable axes: dimensions is empty or a dimension has no axes. | Table, HTML table, Reach |
AE_ERR_413 | 409 | The optimization failed or was cancelled. For a failed job, the origin code is in parentheses in the message. | Get the result of an optimization |
AE_ERR_414 | 400 | A CATEGORIES axis whose parentId is missing or is not a split VARIABLES axis. | Table, HTML table, Reach |
AE_ERR_414 | 410 | The result of the optimization has expired. | Get the result of an optimization |
AE_ERR_415 | 403 | The survey is not available to the user: not contracted, disabled, being loaded or non-existent. The answer is the same in every case. | Variables list, carriers list, tree queries |
AE_ERR_416 | 400 | An unsupported variable in a VARIABLES axis: TEXT subtype, or a CUSTOM_VAR with LOGIC, TOTAL or WEIGHTED. A TARGET_VAR with both id and filterTgl is not an error: filterTgl is used. | Table, HTML table, Reach |
AE_ERR_417 | 404 | The workspace does not exist, is not visible to the user or was already deleted. The answer is the same in the three cases. | Delete a workspace, delete a workspace element |
AE_ERR_418 | 403 | The workspace is shared with the user, not owned by them: only the owner can delete it or its elements. | Delete a workspace, delete a workspace element |
AE_ERR_419 | 404 | The element does not exist in that workspace, belongs to another workspace or was already deleted. | Delete a workspace element |
AE_ERR_420 | 400 | The type of the element cannot be deleted with the API. The message names the type and the types that can be deleted. | Delete a workspace element |
AE_ERR_500 | 500 | The optimization request or state could not be read. | Optimization |
4.3. Codes passed through from the platform
| Code | Status | Meaning | Where |
|---|---|---|---|
TW_ERR_500 | 400 | The API key does not identify a TOM user. The message is always The X-API-Key value does not identify a TOM user. and is not translated. The operations that need an application module answer 403 AE_ERR_408 instead. | Most operations, including the weeks and weightings of a survey and deleting a workspace |
SO_ERR_203 | 401 | The survey is not in the user's profile, or does not exist. | Calculations, saved tabulations and the other survey-scoped endpoints |
SO_ERR_201, SO_ERR_202 | 400 | The survey is disabled or being loaded (201), or has been deleted (202). | Same as above |
WS_ERR_101 | 400 | The workspace does not exist. | Add a survey, create a target, save an evaluation |
WS_ERR_102 | 400 | The workspace has no target with that elementId, or the element is not a target. | Update a target |
WS_ERR_403 | 400 | The workspace is neither owned by the user nor shared with them (for writes, it is not owned by the user). | Get a workspace, get an element, add a survey, create or update a target, save an evaluation |
TREE_ERR_404 | 400 | The tree query returns no node, or the workspace does not exist in a custom tree query. Treat it as an empty result. | Tree queries, user variables, targets, variables, carriers |
DB_ERR_106 | 400 | The saved element cannot be loaded, for example an unknown elementId or workspaceId. | Saved tabulations, combinations |
TB_ERR_118, TB_ERR_119 | 400 | The sliceId does not match the tabulation. | Saved tabulation |
T_ERR_104 | 400 | The table has no statistics to calculate, or a ranking has no statistics. | Table, HTML table, Reach, ranking |
T_ERR_106 | 400 | A statistic that is not valid for the table type, or a statistic id that the calculation engine does not know. | Table, Reach |
TB_ERR_104 | 400 | No variable to tabulate: the table has only a TOTAL variable, or only a STATISTICS axis. When a saved tabulation is read, none of its variables is in the survey. | Table, HTML table, get a workspace element, saved tabulations |
VA_ERR_101 | 400 | An unknown variable, or, in a saved element, variables that do not exist in the survey currently active in the workspace. | Table, get a workspace element |
VA_ERR_102 | 400 | A category that the variable does not have, or a JOINT category without ids. | Table |
CV_ERR_109 | 400 | A user variable (CUSTOM_VAR) that cannot be resolved, for example an id that is not a user variable. In a TREND it is a diagnostic instead (section 4.5). | Table |
SP_ERR_101 | 400 | A carrier id does not exist in the survey. The whole request is rejected: the id is not skipped. | Ranking, evaluation, saving an evaluation, response curve, Reach (REACH_TABLE) |
EV_ERR_103 | 400 | A negative number of insertions. | Ranking, evaluation, response curve |
EV_ERR_104 | 400 | No carrier has a positive number of insertions. | Evaluation, saving an evaluation |
ST_ERR_122 | 400 | The survey does not support media planning, for example a Reach survey. | Ranking, evaluation, response curve |
EV_ERR_108 | 400 | A REACH_TABLE without carriers. | Reach |
RC_ERR_100 | 400 | The survey is not a consumption diary and does not support Reach. In a REACH_TREND, the API checks the survey of the path before calculating and answers with the code and the message of a REACH_TABLE. | Reach capabilities, Reach, table with a Reach type |
RC_ERR_106, RC_ERR_107 | 400 | A diary edge axis uses values or time ranges that the survey does not have. | Reach |
RC_ERR_108 | 400 | targetMedia includes carriers that the survey does not have. | Reach |
RD_ERR_100 | 400 | A REACH_DUPLICATION table without a second CARRIERS axis. | Reach |
TG_ERR_113 | 400 | target or targetBase has an id that does not identify a saved target. In ranking, evaluation and response curve, only targetBase gives it: an unknown target.id is 404 AE_ERR_406. | Table, Reach (REACH_TREND included), ranking, evaluation, response curve |
TR_ERR_101, TR_ERR_103 | 400 | A TREND without a SOURCES axis (101) or without a DIFFERENCES axis (103). A REACH_TREND without them is AE_ERR_412 instead. | Table, HTML table |
TR_ERR_105 | 400 | No survey wave of a trend is valid: none is available to the user, or their weeks or weighting are not valid. | Table, Reach (TREND, REACH_TREND) |
TR_ERR_106 | 400 | extraParams.trendCategoriesMode is not a valid value. | Table, Reach (TREND, REACH_TREND) |
TR_ERR_109 | 400 | No survey wave is left after checking the variables of the table and, in a REACH_TREND, the Reach checks of each wave. | Table, Reach (TREND, REACH_TREND) |
TGL_ERR_101 | 400 | The TGL expression uses a variable or category that does not exist. | Create or update a target, and the filterTgl of a calculation: table, Reach, ranking, evaluation, saving an evaluation, response curve |
TGL_INVALID | 422 | The TGL expression cannot be parsed, or uses a variable without a category or a condition. | Create or update a target, and the filterTgl of a calculation: table, HTML table, Reach, ranking, evaluation, saving an evaluation, response curve |
JOB_USER_LIMIT_REACHED | 429 | The user already has the maximum number of queued background jobs. The text of the message is not part of the contract. | Submit an optimization |
JOB_NOT_FOUND | 404 | The job does not exist, belongs to another user or was deleted. The cases cannot be told apart. | Status and result of an optimization |
JOB_RESULT_EXPIRED | 410 | The result of the job has expired. Handle it like AE_ERR_414. | Result of an optimization |
The calculation engine also returns its own codes (for example other T_ERR_*, TG_ERR_* or TGL_ERR_* codes). Their messages can be in the language of the user: base your handling on the code.
4.4. Origin codes of a failed optimization
When the result of a job is 409 AE_ERR_413, the message of a failed job carries the original code in parentheses, for example The optimization job failed (PO_ERR_100). A cancelled job has no code.
| Origin code | Cause |
|---|---|
PO_ERR_100 | The definition was rejected when the job started: another optimization of the same user was active, no candidate carrier had a price, a rule was broken (maxInsertions lower than minInsertions, step not greater than 0, COVERAGE_PERCENT above 100, minMarginalCoverage outside 0 to 100) or no objective had a value. |
PO_ERR_101 | The engine could not be reached or answered with an error. |
PO_ERR_102 | The engine did not complete any iteration. |
PO_ERR_104 | Iterations ran, but no plan could be read. |
TGL_ERR_..., TG_ERR_... | The target or the base (targetBase) could not be resolved. |
EXECUTOR_LOST, JOB_RETRY_LIMIT_REACHED, EXECUTOR_CHAIN_ERROR | An infrastructure failure. |
The list is not exhaustive. See Asynchronous optimization.
4.5. Diagnostics of a survey wave
In a TREND or REACH_TREND, a survey wave that cannot be calculated is not an error: the response is 200, the other waves are calculated, and diagnostics reports the wave. diagnostics.level is the worst level of its diagnostics.
| Diagnostic code | Level | Cause |
|---|---|---|
TR_ERR_107 | WARNING | The wave is left out: it is not available to the user, its survey has weeks and the wave sends none or one the survey does not have, or its weighting is not one of the survey. Take the values from GET /api/v2/survey/{surveyCode}/weeks-and-weights. |
RC_ERR_112, RC_ERR_113, RC_ERR_115, RC_ERR_116 | WARNING | (REACH_TREND) The wave comes without values: its survey does not have the carriers, the diary filters or the target media requested, or it has no Reach data. |
CV_ERR_109 | WARNING | (TREND) A user variable (CUSTOM_VAR) of the table cannot be resolved in the wave. |
A saved target that exists but does not resolve in the survey of the path is left out of every wave with an ERROR diagnostic, and the figures are those of the whole population. With no valid wave left, the request fails with 400 TR_ERR_105.
5. Retry guidance
- Do not retry
4xxresponses without changing the request. The exceptions are409AE_ERR_412(the optimization has not finished: poll again, waiting at leastretryAfterSeconds) and429(retry when some of your jobs have started or finished). 500on a calculation. It can mean that the request took longer than the time limit. Reduce it (fewer carriers, statistics or axes) before you retry.500on an operation that creates data (workspaces, targets, saved evaluations, optimization jobs). It may or may not have created it. Check before you retry: the creating operations are not idempotent.- A delete is final. After a
204, repeating the same delete answers404. Treat that404as the confirmation that the workspace or element is gone. - A submitted optimization is a new job each time. Do not resubmit a request that timed out without checking whether the first one was created.
- Do not loop on a
401or403. They tell you that something is wrong with the key, the module or the survey.
6. Troubleshooting by symptom
| Symptom | Probable cause | What to do |
|---|---|---|
401 E401 on every call | The X-API-Key header is not being sent. | Check the header in a raw request. |
401 SO_ERR_203 on a table | The survey is not in your profile, or its code is wrong. | Take the code from GET /api/v2/users/surveys. |
403 AE_ERR_415 on variables or carriers | The survey is not available to you, even if it is in a workspace. | Check the survey list. Surveys that are disabled or being loaded are not listed. |
403 AE_ERR_408 | The module is not enabled for the user. | See Authentication and access for the module of each operation. |
My target.id is ignored on a table | The same target also has filterTgl, which wins. | Send only one of them. |
| A code from a tree query does not work | You used the node id, which is opaque, instead of the code. | Use the code of the node. |
nextTableLink does not work when called | The links of a saved tabulation cannot be called as they are. | Take the last segment of the link and pass it as sliceId, or list the slices with the combinations operation. |
The HTML table ignores decimals or locale | The HTML operation ignores dataType, locale and decimals. | Use the JSON operation for formatted cells. |
| A misspelled optional field has no effect | Most request bodies, and the nested objects of a table request, ignore unknown fields. | Compare your field names with the reference. The strict bodies do not ignore them: the table model answers 400 AE_ERR_411 and the optimization request 400 AE_ERR_400, with the field (see Limits and conventions). |
An optimization ends FAILED | The result call returns 409 AE_ERR_413 with the origin code in the message. | See the table in section 4.4. |
| A survey wave is missing from a trend, or has no values | The wave was left out or could not be calculated, and diagnostics says why (TR_ERR_107, RC_ERR_*). | See section 4.5. Take weeks and weightings from GET /api/v2/survey/{surveyCode}/weeks-and-weights. |
Two waves of a REACH_TREND give identical columns | They are waves of the same survey that differ only in their weeks or weighting. | Nothing to fix: in a REACH_TREND, weeks and weighting only decide whether a wave is calculated, and do not change the Reach figures. |
404 AE_ERR_417 when you repeat a delete | The workspace was already deleted. The same answer is returned for a workspace that does not exist or that is not visible to you. | Treat the second 404 as done, or check GET /api/v2/workspaces. |
404 AE_ERR_419 when you delete an element | The element was already deleted, or it lives in another workspace. | Check the workspaceId and the id of the element. |
403 AE_ERR_418 when you delete | The workspace is shared with you and you are not its owner. | Only the owner can delete it or its elements: ask the owner. |
400 AE_ERR_420 when you delete an element | The element is a folder, the menu, a map or another type that cannot be deleted. | See the types in Workspaces, targets and reusable elements. |
429 JOB_USER_LIMIT_REACHED | You have 50 queued background jobs. | Wait until some start or finish. |
206 on a tree query | The result has more than 3,000 nodes and was truncated. | Narrow the query with an anchor, types or text. |
400 TREE_ERR_404 on a search | No node matches. | Treat it as an empty result. |
7. Language of the messages
The errorMessage of an error can be in the language of the user behind the key. Some messages of the platform are fixed in one language and are not translated. Never branch on the text of a message: use errorCode.
8. Contacting support
When you contact your TOM platform representative about an error, send:
- The UTC date and time of the call.
- The method and the path (without query parameters that contain personal data).
- The HTTP status and the
errorCode, and theerrorMessageif it helps.
Never send your API key.