VAST macros / Cachebusting and error
[ERRORCODE] VAST macro
Short answer: The numeric VAST error code, substituted only inside an Error URI. Introduced in VAST 3.0.
What it means
Resolves to the code the player chose from the VAST error table, such as 301, 303, 402, or 405. The macro has a defined value only in an Error element. Anywhere else the player sends the brackets as text.
Example value
After the player substitutes the macro, [ERRORCODE] becomes something like:
303Before and after the player substitutes it
The first line is the URL in the tag. The second line is the request the player sends once it has a value.
https://ad.example.com/error?code=[ERRORCODE]
https://ad.example.com/error?code=303The only element that defines it
[ERRORCODE] resolves to the integer the player picked from the VAST error table: 301 when a wrapper URI did not answer, 303 when the chain came back empty, 402 when a media file timed out, 405 when a media file arrived and would not play. The macro has a value only inside an Error element. VAST 3.0 introduced that element and the macro together. A 2.0 player has no reason to substitute it.
An Impression URL, a quartile URL, or a click URL that contains [ERRORCODE] is the wrong context. On a play that succeeds, nothing ever substitutes it, so the log line still contains the brackets. That is the macro working as specified. It is not a sign the player forgot. Move it to Error if you want the number.
What the request looks like when a real code fires
The tag carries the token. The player requests the Error URL after it has chosen a code, with the token replaced. One error produces one code. The macro does not include the spec sentence, the element name, or the URL that failed. Those have to be recovered from the tag and from the inspector.
[REASON] is a different macro, for a free-text note on some errors. A player may fill [ERRORCODE] and leave [REASON] empty, or the reverse. Do not treat a missing reason string as a missing code. Read the integer first, then open that code's page.
Brackets that survive into the log
event URLs and impression URLs are requested on the happy path, when there is no error code to insert. The brackets remain. Error URLs are requested on the failure path. If your error endpoint shows [ERRORCODE] as text, the player did not recognise the macro: the case is wrong, the player is older than 3.0, or the token was percent-encoded in the tag so it no longer matches the pattern the player searches for.
[errorcode] in lowercase is not the macro. The player looks for the uppercase token. vastlint flags the wrong case, an unknown token, and this macro used outside an Error URI.
The impression is the wrong element. The Error URL has already been encoded, so the player no longer sees the token.
<Impression><![CDATA[https://t.example.com/i?err=[ERRORCODE]]]></Impression>
<Error><![CDATA[https://ad.example.com/error?code=%5BERRORCODE%5D]]></Error>VAST XML fragment only. This excerpt belongs inside a complete VAST document, so standalone validation will fail until it is wrapped in a full <VAST>response.
Where it is valid
Only <Error> URIs. Introduced with the error element in VAST 3.0.
Macros are case-sensitive and substituted only inside URL fields. A macro written in the wrong case, or placed where it has no defined value, is sent to the server as literal text instead of a value.
Using it in a tag
<Error><![CDATA[https://ad.example.com/error?code=[ERRORCODE]]]></Error>VAST XML fragment only. This excerpt belongs inside a complete VAST document, so standalone validation will fail until it is wrapped in a full <VAST>response.
Related vastlint rules
- VAST-2.0-macro-unknown: URL contains a [MACRO] that is not a recognised IAB VAST macro
- VAST-2.0-macro-lowercase: Recognised macro is not uppercase — players match macro names case-sensitively
- VAST-2.0-macro-wrong-context: Context-restricted macro ([ERRORCODE]/[REASON]) used where it has no defined value
Related macros
- [REASON]: Why a verification script was not executed (code 1, 2, or 3).
- [CACHEBUSTING]: A random value that prevents caching of a tracking request.
Validate your macros
vastlint flags unknown, mis-cased, deprecated, out-of-context, and unencoded macros in any tracking, click, error, impression, or media URL:
# CLI: exits non-zero on errors, ideal for pipelines
vastlint check creative.xmlUse the right tool for this failure
If you already have the resolved XML, run a pure spec check. If you only have a live tag URL, test that endpoint first. If the failure happens in the wrapper chain, inspect each hop.