Skip to content
P4 Software P4 Software / BarcoderX English

Add these docs to Claude

Ask Claude questions about these docs. Claude reads the published pages and links you back to them. Copy this address:

https://p4-software.opendocs.page/mcp

In claude.ai or Claude Desktop: open Settings, then Connectors, choose Add custom connector and paste the address.

In Claude Code, run:

claude mcp add --transport http docs https://p4-software.opendocs.page/mcp

The label service

The label service

Applies to: BarcoderX Basic and Ultimate

Status: Built, not yet released. The first slice of the label service exists and is tested, but nothing is released yet and there is nothing to download. It is a small program that you run yourself. It draws one label from a template with the label engine and answers with a PNG file, or with the ZPL printer commands of the label. The pictures and the commands carry the evaluation mark, and the service is not for production use. The rest of the web API is planned: see Web API. Anything marked "planned" is not usable yet.

The label service takes a label template as JSON and gives back a picture of the label as a PNG file, or the printer commands of the label (see ZPL output), or a list of problems. It is the first built part of the web API, and it is meant for trying BarcoderX and for a demonstration page. It stores nothing: not the template, not the picture. It draws only through the label engine, so what it makes is what the engine makes. See The label engine and PNG output.

Running it

You start the service by double-clicking its program. There are no command-line switches and no environment variables to learn.

  • The first time, the program writes a file called settings.json next to itself, with a comment above every setting. It tells you so in the window.
  • To change something, edit settings.json, save it and start the program again. If you break the file, delete it: the program writes a fresh copy with safe values.
  • If a setting is wrong, the window says which one and where, in plain words, and waits for Enter before it closes, so that you can read it.
  • Without changes, the service listens only on this computer, at http://127.0.0.1:5187, and runs open to everyone who can reach it (publicDemo is true in the starter file).

The service speaks plain http. For use from other computers, put a web server that handles https in front of it. See "If you host the service" below.

Asking for a picture

Send a POST to /api/v1/render/png with the template as the body.

curl -X POST "http://127.0.0.1:5187/api/v1/render/png?imageType=color" -H "Content-Type: application/json" --data-binary @label.json -o label.png

Here label.json is a template, for example the smallest template of The label template format. It gives a picture 799 by 400 dots at 203 dots per inch. If you set an API key, add -H "Authorization: Bearer <your key>". On Windows, type curl.exe.

Part of the requestWhat it does
Content-TypeMust be application/json, with no character set or with utf-8. Anything else is refused with 415.
The bodyThe template as JSON text. At most 262,144 bytes by default.
dpi in the addressThe resolution to draw at, in dots per inch. Optional. Without it, the resolution written in the template is used. It must be inside the limits of the service (96 to 600 by default).
imageType in the addressThe kind of picture. Optional. blackAndWhite is the default: what a printer would print, with no smoothing. gray and color have smooth edges, for looking at on a screen.
Accept-Languageen or es. The messages of a problem answer come in that language. English is the default.
AuthorizationBearer and your key. Needed only when the service has an apiKey.

A setting in the address that the service does not know, a repeated one, or a value that cannot be used, is refused with 400. The names are case sensitive.

Asking for printer commands

Send a POST to /api/v1/commands?dialect=zpl with the template as the body. It is the same handler as the picture route, so the key, the content type, the size of the body, the places for drawing, the rate limits, the time limit and the write deadline are the same, and so are the problem answers. The settings of the address are dialect (required: zpl is the only value, in lower case) and dpi (as for the picture). imageType is not a setting of this route and is refused with 400 like any other name that the route does not know.

curl -X POST "http://127.0.0.1:5187/api/v1/commands?dialect=zpl&dpi=203" -H "Content-Type: application/json" --data-binary @label.json -o label.zpl
  • 200. The body is the ZPL commands of the label as plain ASCII text, with Content-Type: text/plain; charset=utf-8. The header BarcoderX-Warnings lists the codes of the notes, and BX5130 (the label is sent as one picture) comes first. While no license is registered it also lists BX9001, and the commands carry the evaluation mark. The commands are at most limits.maxCommandsBytes bytes; a label that would need more gets a 422 with BX6008 and BX5112 in errors. See ZPL output for what is in the commands.
  • As a JSON document. Send Accept: application/json and the answer is a JSON document instead of plain text: dialect, commands (the same text), diagnostics (the notes of the engine in the language of the request, each with code, severity, title and message), warningCodes (the same codes as the header) and marked. A request with no Accept header, with */*, with text/plain, or with application/json at weight 0 gets the plain text, as before. The answer says Vary: Accept. The JSON form is a little larger than the plain text (the line ends are escaped, and the notes are added), and it is made in memory outside the budget of the answers for a moment (see "How much memory to give the service" in Deploying the label service); if it is larger than the whole pool of answers, the answer is 413 with BX6019 and no Retry-After, and the plain text is still sent. The commands as bytes for a download are the plain text answer.
  • Not run on a printer. No form of the commands has been run on a physical printer yet.

The answer

  • 200. The body is the PNG file, with Content-Type: image/png. The resolution is written in the file. The headers BarcoderX-Image-Width and BarcoderX-Image-Height give the size of the picture in dots (one dot is one pixel), so that a page can draw it at a whole-number zoom before it decodes the file. The header BarcoderX-Marked (on a picture and on printer commands) says true when the engine marked the label with the evaluation mark and false when it did not. When the engine had warnings or notes about the label, the header BarcoderX-Warnings lists their codes, separated by commas, for example BX3902,BX3906. It holds codes only, never text from the template. See Diagnostic codes.
  • Any other status. The body is a problem document (application/problem+json, RFC 9457) in the language of the request: type, title, status, detail, code, traceId and, when the template had problems, an errors list. Each entry of the list has a code, a severity, a title, a message, the elementId and the pointer to the place in the template, and the args.
  • Every answer carries Api-Supported-Versions: v1, Cache-Control: no-store and X-Content-Type-Options: nosniff. When a proxy that you list in network.trustedProxies says that the visitor used https, every answer also carries Strict-Transport-Security: max-age=15552000 (six months, without includeSubDomains and without preload); it is never sent on plain http (see network.sendStrictTransportSecurity). After a problem answer the connection is closed.
StatusCodeWhat it means
400BX6002, BX6003, BX6013A setting of the address is not known or not valid, or the body is not JSON text.
401BX6010The key is missing or wrong. The answer carries WWW-Authenticate: Bearer realm="BarcoderX".
403BX6024Only when network.edge.mode is azureFrontDoor: the request did not come through the front door of the service (no or wrong Front Door ID, no or wrong host name, or not from your web server). Nothing about the front door is told in the answer. It is answered before the body is read, and uses no caller's allowance.
404BX6011Nothing is served at that address.
405BX6012The method is not accepted. The answer carries Allow.
408BX6017The whole template did not arrive within limits.bodyReadMilliseconds, or it arrived more slowly than the server accepts (see that setting). The answer is sent with Connection: close.
413BX6000, BX6019The template is larger than the limit (BX6000), or the answer is larger than the most the service holds for one answer (BX6019, only for printer commands as JSON): there is no Retry-After, because asking again gives the same refusal. Ask for plain text, or make the label smaller.
415BX6001The content type is not JSON in UTF-8.
422BX6004, BX6007, BX6008The resolution is not accepted, the request took too long, or the template has problems, which are listed in errors. When the printer commands would be over limits.maxCommandsBytes, errors holds BX5112, or BX6025 (the same finding in words for a visitor) when publicDemo is true.
429BX6005, BX6006, BX6014, BX6015, BX6016, BX6018, BX6023This caller made too many requests (BX6005), or too many requests for the pictures of single elements (BX6023), every place for drawing is taken (BX6006), all callers together made too many (BX6014), this caller already has a request being served (BX6015), too many answers wait to be taken by their readers (BX6016), or too many templates are arriving at once (BX6018). The answer carries Retry-After in seconds, worked out from the limit that was reached: wait that long.
500BX6009An unexpected problem. The answer gives no detail; give the trace id to support.

The texts of these codes, in English and Spanish, are in Diagnostic codes.

The type member of a problem document is an address under docs.barcoderx.example, followed by the code. It is a placeholder: the real domain of the documentation is not decided yet, and nothing in the service or in the .NET client follows it. Use the code.

What a caller may have at the same time

  • One request at a time. By default each caller (see "Who the caller is" below) may have one request being served, from the first byte of the template to the last byte of the answer. A second request while the first is still going is refused at once with 429 and BX6015, before anything is read. The setting is limits.maxRequestsInFlightPerClient.
  • The template is read before a place for drawing is taken. The whole template must arrive within limits.bodyReadMilliseconds (5,000 by default), and its size is limited as the bytes arrive. A caller that sends slowly holds only its own place and one connection, for at most that time, and is then stopped with BX6017. It never holds a place for drawing.
  • A place for drawing only while the label is made. The few places for drawing are held while the label is laid out and drawn, and given back when the answer is ready. An answer that waits for a slow reader waits in a pool of its own (limits.outputBudgetMegabytes), and a slow reader can only hold its own answer. When the pool is full the request is refused with BX6016 after its label was made.
  • Connections. One caller may have limits.maxConnectionsPerClient connections open at the same time (16 by default). A connection over that number is closed at once, with no answer, before a byte is read. A refusal that is sent before the whole template has arrived is finished at once, and the service then waits one second for the rest of the template and cuts the connection if it has not come, so a refused caller that keeps sending slowly does not keep its connection. Connections from a proxy that you list in network.trustedProxies are not counted: limit them at the proxy.
  • Requests. Every request of a caller, a request for a missing address included, counts against its own limit rateLimit.requestsPerMinutePerClient. Only the requests that reach a route that draws count against the limit of all callers together, rateLimit.requestsPerMinuteAllClients, so a flood of requests for missing addresses cannot use up the quota of everyone. The health checks are never counted.
  • Wait times. A refusal tells you how long to wait. For a rate limit it is the time until the next request is allowed. For BX6018 it is the time to send a template. For BX6006 it is about the time to lay out a label (limits.engineMilliseconds) and the time limit of a request (limits.renderMilliseconds) together, which is how long a place for drawing is held in practice. For BX6015 it is the time to send the template, those two and the write deadline together, and for BX6016 it is the write deadline.

Checking a template

The service stores no template. Two routes work on a template that you send, for an editor or a build step that wants to know what is wrong with it, or what its canonical text is. Both take the template as the body (Content-Type: application/json), no setting in the address, and the same key, size limit, time to send and per-caller limit as the picture route. They draw nothing, so they do not use the limit of all callers together, but, once the template has arrived, they take a place for drawing while the service works on it, as a picture does, because reading a large template costs memory, so a service with a large limits.maxBodyBytes needs a larger limits.memoryBudgetMegabytes, and an editor that sends several requests at once needs a higher limits.maxRequestsInFlightPerClient.

  • POST /api/v1/templates/validate. The answer is always 200 when the template was received: valid (false when the template could not be read or a finding is an error) and diagnostics, every finding in the language of the request (Accept-Language), each with code, severity, title, message, elementId, pointer and args. A finding of the reader about the text (a character that JSON does not allow, for example) carries the line and position where the problem starts in its args. Text that is not JSON gives 200 with valid false, not an error status, because the answer is the findings. A body over the limit is 413, a content type that is not JSON is 415.
  • POST /api/v1/templates/convert. The answer is the canonical text of the template (Content-Type: application/json): the one fixed form in which BarcoderX writes a template, with every element and the members that the model keeps. Converting the canonical text gives the same text. The canonical text is never larger than limits.maxBodyBytes, so it can always be sent again to this service; a template whose canonical text would be larger is refused with 422 and the finding BX1130. A template that is not valid is a problem with its findings in errors, as on the picture route (422, or 400 for text that is not JSON). No older version of the template format is converted yet, so today this is the canonical form of a template that is already in the current format.

Pictures of single elements

An editor that shows a label needs a picture of each element on its own, with the box it takes on the label and, for a barcode, the size of its symbol. POST /api/v1/render/elements gives them. The service stores nothing: the template travels in the request, as it does for every other route, and the answer is made from it.

The body is JSON with these members: template (the template as an object, a partial one is fine), ids (the ids of the elements to draw: 1 to 64, each 1 to 128 characters, no repeats), and, if you want them, dpi (96 to 600; an element is drawn at the smaller of this and 300), culture (en or es, the language of the findings; without it the service follows Accept-Language) and record (a data record as an object). A member that is not known, is repeated or is not valid is refused with 400 and the code BX6020, which names the member. The key, the size limit, the time to send, the media type and the limits of the caller are the ones of the picture route, and a request for elements counts against the limit of all callers together as a picture does.

The answer is 200 with engineVersion and items, one item for each id that was asked for, in the order asked. Each item has:

  • status: ok (drawn), error (it could not be drawn or its picture could not be sent: see its diagnostics), notFound (the template has no element with that id) or skipped (an element of a kind that the engine does not draw on its own yet, such as a line or an ellipse, or one whose content comes from data).
  • For an ok item: form (png) and png (the picture as base 64 text of a PNG file with one bit for each dot, cropped to the box of the element); bounds (unit and box in the unit of the page, and dots at the resolution of the picture, so the picture is exactly that size); symbol for a barcode (the size of the symbol in the unit of the page and in dots, and the width of a module in dots); and hash.
  • diagnostics: the findings about the element, in the language asked.

The hash is the same for the same drawing and changes with everything that influences it: the element, the template, the data, the language, the resolution, the version of the engine and whether the picture is marked. A client can keep a picture under its hash. An element that fails does not fail the request.

The evaluation mark. Without a license that allows it, every picture carries the evaluation mark merged into its dots, and the answer says so: the header BarcoderX-Marked is true, and BarcoderX-Warnings lists the note about the license (for example BX9001, no license is registered). The service decides this from its own license state, and nothing in a request can change it. The mark is a deterrent, not a lock.

Limits. At most 64 ids; at most 4,000,000 dots in the picture of one element and 16,000,000 in all the pictures of one request (an element past them is error with its diagnostics); at most 512 KB for the PNG of one element (BX6021); at most 8 MB for the whole answer (when the next picture would pass it, that one and the ones after it are left out with BX6022). GET /api/v1/meta/limits publishes these figures as maxFragmentIds, maxFragmentDots, maxFragmentDotsPerRequest, maxFragmentBytes and maxFragmentsAnswerBytes. The time limit of a request (limits.renderMilliseconds) does not stop the drawing of the elements: the mark is merged into the dots by the same call, and an unlicensed caller must not be refused for time that a licensed one does not spend. The drawing is stopped by the engine's own deadline (limits.engineMilliseconds), and the writing of the pictures gets the time limit from the moment the drawing ends. The answer is never kept by a cache (Cache-Control: no-store); keep pictures by their hash instead. A request for elements holds more memory than a picture, so it takes more than one of the places for drawing: with the default settings there are four places and it takes two, so a picture is still drawn and a second request for elements still runs, and a third request for elements is refused at once with BX6006 while they run (see Deploying the label service). A caller may also make only a few requests for elements a minute (rateLimit.elementRequestsPerMinutePerClient, 6 by default, on top of its other limit): one that asks more often is refused with BX6023 and told how long to wait, and GET /api/v1/meta/limits publishes the number as elementRequestsPerMinutePerClient.

The other routes

RouteWhat it gives
GET /api/v1/meta/limitsThe limits of this service as JSON: maxBodyBytes, maxElements, maxCharactersPerText, maxCharactersPerLabel, maxBlackAndWhitePixels, maxColorPixels (also for gray), maxSideDots, maxOutputBytes, maxCommandsBytes, minDpi, maxDpi, renderMilliseconds, bodyReadMilliseconds and requestsPerMinutePerClient, requestsPerMinuteAllClients, maxRequestsInFlightPerClient, maxConnectionsPerClient, responseWriteMilliseconds, elementRequestsPerMinutePerClient, maxFragmentIds, maxFragmentDots, maxFragmentDotsPerRequest, maxFragmentBytes and maxFragmentsAnswerBytes (the limits of the route for single elements), maxCoordinateMillimeters and maxQuietZoneModules (the two limits that the bounds named coordinateMagnitude and quietZoneModules in the element descriptors refer to). A page can read them to check a template before it sends it and to know how fast it may send.
GET /api/v1/meta/versionproduct, apiVersions and build.
GET /api/v1/meta/licenceThe license state of this service: state (unlicensed, grace, evaluation or licensed), outputMarked (true when the state is unlicensed, which means all output is marked: every picture and set of commands carries the evaluation mark; it does not cover a single label that is marked because it uses something the license does not include, such as a barcode type it does not cover, which can happen on a licensed service), and, only on a service that has a key and only for a caller that has shown it, expiresOn and updatesUntil (dates as yyyy-MM-dd, left out when there is none). The dates reveal how long the license runs and how long it gets updates, so a service that is open to everyone does not give them. It never gives the key, the id of the license or the name of the licensee. The answer is private: a shared cache must not keep it. On a service that has a key, a caller that has shown it also gets entitlements (the feature ids the license grants now, none when the output is marked), findingCodes (the diagnostic codes of the findings, such as BX9004), and nextChangeOn with nextChangeKind (expiry, graceEnd or updatesEnd), left out when no change is dated. They reveal the terms of the license, so a service that is open to everyone does not give them.
GET /api/v1/printer-dialectsThe printer languages the commands address writes, as items: id (the value of dialect), displayName in the language of the request and fidelity (raster: the whole label is sent as one picture). Today the list is zpl.
GET /api/v1/printer-profilesThe printer profiles, as items: id, displayName, dialect and dpi. Today these are zpl-generic-203, zpl-generic-300 and zpl-generic-600. Nothing about a printer model is listed: no width, memory or fonts, because they are not measured yet.
GET /api/v1/meta/elementsThe element descriptors that the panels of the editor are built from: version (a hash of the content; it is also the ETag) and kinds (text, barcode, line, box, ellipse), each with its groups of properties. A property has its name, path, labelKey, kind, unit, shape, isRequired, isOptional, acceptsExpression, isDerived, unitFollows, range, default, values (each with key and labelKey), shownWhen (conditions on other properties) and members (the parts of a composite). They carry resource keys for every name and never the texts: the editor holds its own labels, so the answer does not depend on the language. A bound of a range is a number or a multiple of a limit that the service sets (coordinateMagnitude in millimeters, quietZoneModules): read the numbers in GET /api/v1/meta/limits.
GET /api/v1/barcodes/symbologiesThe symbologies that a barcode element may use, as items: id (the value of symbology), aliases, displayName in the language of the request, family, tier (basic or ultimate), availability (implemented, or planned: listed but not drawn yet), sampleContent for a newly added barcode, and the options of the symbology (name, kind, unit, minimum, maximum, defaultValue, enumKeys, shownWhen, and usableInTemplates: false while the engine ignores the option). Only symbologies that may be published are listed.
GET /health/live and GET /health/ready{"status":"ok"} and nothing else. They need no key.

The routes /meta/licence, /meta/elements, /printer-dialects, /printer-profiles and /barcodes/symbologies answer with an ETag and Cache-Control: no-cache (private, no-cache for the license state). Send the tag back in If-None-Match and an unchanged answer is 304 with no body. The names follow Accept-Language (en or es), and the tag differs by language, except for /meta/elements, which holds no text and has one tag.

All routes except the two health checks need the key when the service has one. Every product route is under /api/v1. There is no OpenAPI document yet.

From a .NET program

A typed .NET client for both routes is built and tested. For the picture it takes the template text and the options (the resolution, the kind of picture and the language), and gives back the PNG bytes and the codes of the warnings, or the problem document and the number of seconds to wait. It throws only for a network failure or a canceled request, never for a problem that the service reports. RenderElementsAsync asks for the pictures of single elements: it takes the template, the ids and the options (resolution, language and a data record) and gives back the list of elements, whether the pictures are marked and the codes of the warnings, or the problem document. RenderCommandsAsync does the same for the printer commands (the options are the printer language, the resolution and the language of the messages). Like the rest, it is not released yet.

The settings file

The file is JSON with comments. A name that the program does not know is an error, so a typo is found and not ignored. A missing setting keeps the safe value. Every number below is a first choice that the builders made. It has not been confirmed yet and can change before the first release.

SettingDefaultWhat it does
listenAddresshttp://127.0.0.1:5187Where the service listens. Only http, with an IP address or localhost. Use 0.0.0.0 to let other computers reach it.
publicDemotrue in the starter filetrue runs the service open to everyone, on purpose. false needs an apiKey.
apiKeyemptyA secret of at least 32 characters. Every request must send it as Authorization: Bearer <key>. Leave it empty only when publicDemo is true.
logLevelInformationInformation writes one line for each request: status, route, sizes, time, the code of a problem and the trace id. Warning writes only problems. Never the content of a template.
cors.allowedOriginsemptyWeb sites whose pages may call the service from a browser, for example https://barcoderx.com. Empty means none. A star is refused. Cookies and credentials are never allowed.
network.trustForwardedHeadersfalseWhether to read the address of the caller from a proxy. Turn it on only with network.trustedProxies set. See "Who the caller is" below.
network.sendStrictTransportSecuritytrueWhether to tell browsers to use only https for six months (the Strict-Transport-Security header, max-age=15552000, never includeSubDomains or preload). The service speaks only http, so it sends the header only when network.trustForwardedHeaders is true and a proxy listed in network.trustedProxies says X-Forwarded-Proto: https (the entry at the right end of the header is the one believed). It is then on every such answer, errors and health checks included, and never on an answer to a request that does not come that way. Set false to send nothing.
network.trustedProxiesemptyThe proxies you trust, each as an address (10.0.0.5, 2001:db8::5) or a range (10.0.0.0/8, 2001:db8::/32), at most 32. A malformed entry stops the service from starting (a number with a leading zero, such as 010, is refused: the platform would read it as octal). "Any address" (0.0.0.0 or ::) and a range that covers every address or almost every address (0.0.0.0/0, ::/0, any range wider than /8 for IPv4 or /7 for IPv6) are refused unless network.acceptAnyProxyAddress is true. The proxies you list here are also not counted by the cap on connections, whether or not network.trustForwardedHeaders is on.
network.acceptAnyProxyAddressfalseLeave it false. It only allows a range that covers every address in network.trustedProxies, which makes every caller a trusted proxy that can choose its own address.
network.edge.modeoffoff or azureFrontDoor. With azureFrontDoor the service answers only requests that came through your Azure Front Door: see "Azure Front Door in front of App Service" in Deploying the label service. It needs network.trustForwardedHeaders true, the ranges of your web server in network.trustedProxies, network.trustedProxyHops 1 and network.acceptAnyProxyAddress false, or the service does not start.
network.edge.frontDoorIdemptyThe Front Door ID of your profile (36 characters with hyphens), as the portal shows it. Needed when the mode is azureFrontDoor. Treat it like a password: it is never logged or shown by the service, and it belongs in the file next to the program only.
network.edge.hostsemptyThe host names your visitors type, 1 to 8, letters, digits, hyphens and dots only (an international name in its xn-- form), compared without regard to case. Needed when the mode is azureFrontDoor.
network.trustedProxyHops1How many listed proxies in a row, counted from the connection, are believed when they name the next address in X-Forwarded-For (1 to 8). 1 is the proxy the connection comes from. Use 2 only when a listed front end is in front of a listed proxy. See "Who the caller is" below.
rateLimit.requestsPerMinutePerClient20Requests one caller may make in a minute on average (1 to 600). A caller may send that many at once, and gets one more every minute divided by the number.
rateLimit.requestsPerMinuteAllClients600Requests all callers together may make in a minute on average to the routes that draw (1 to 6,000), counted the same way.
rateLimit.elementRequestsPerMinutePerClient6Requests for the pictures of single elements (POST /api/v1/render/elements) that one caller may make in a minute on average (1 to 600), counted the same way and in addition to rateLimit.requestsPerMinutePerClient. It is lower because such a request uses more of the memory for drawing than a picture does; the routes that draw a label keep their own limit. A refused caller gets BX6023 and is told how long to wait.
limits.maxBodyBytes262,144Bytes of a template (1,024 to 10 MB). A service that is open to everyone (publicDemo is true) accepts at most 262,144 and refuses to start with more. For the web editor, set publicDemo to false, give the service a key, and raise it (2,097,152 is 2 MB). A larger body needs more memory: the memory budget below counts 60 times the body limit for each request, on top of its picture and its text, so raise limits.memoryBudgetMegabytes to keep the same number of labels drawn at once. At the default budget (512 MB), a service with a 2 MB limit draws one label at a time, and another request that arrives meanwhile is refused with BX6006.
limits.maxElements200Elements in a template.
limits.maxCharactersPerText2,000Characters in one text or barcode content (up to 50,000).
limits.maxCharactersPerLabel5,000Characters of text in all elements of a label (up to 50,000).
limits.maxBlackAndWhitePixels9,000,000Dots, width times height, of a black-and-white picture (up to 64,000,000). The most that the picture, the printer commands and the memory of a render depend on. The free public playground at barcoderx.com uses about 4,000,000, which keeps the largest answer near 1 MB (4 x 6 and 4 x 8 inches at 300 dpi still fit); a larger label is refused at once, before it is laid out, with BX3901, which says to change the size or the resolution.
limits.maxGrayPixels, limits.maxColorPixels2,500,000Dots of a gray and of a color picture (up to 64,000,000).
limits.maxSideDots8,192The longest side, in dots (up to 65,536).
limits.maxOutputBytes2,000,000Bytes of the PNG file in the answer (1,024 to 256,000,000).
limits.maxCommandsBytes16,777,216Bytes of the ZPL commands of one label in the answer of the commands route (1,024 to 67,108,864). The dots of the label are limited by limits.maxBlackAndWhitePixels, and the size of the commands follows from the dots (2 hexadecimal characters for each 8 dots, about a quarter of a byte for each dot), so with 9,000,000 dots no answer is larger than about 2.27 MB. The free public playground uses 2,500,000, a written ceiling above that. A label over it is refused before anything is drawn.
limits.minDpi, limits.maxDpi96 and 600The resolutions accepted. The engine itself draws from 96 to 1,200.
limits.engineMilliseconds1,000Time to lay out one label, or to draw the elements of one request.
limits.renderMilliseconds2,000Time to read a template, once it has arrived and a place for drawing is taken, and, counted again from the end of the layout, time to draw the picture or make the commands. The layout itself has limits.engineMilliseconds; the time that the evaluation mark takes is in neither, so that a service without a license does not refuse what a licensed one serves.
limits.bodyReadMilliseconds5,000Time a caller has to send the whole template (100 to 60,000). A caller that sends more slowly is stopped with BX6017. The server also stops a sender that sends, on average, fewer than 240 bytes a second once its first 5 seconds are over, whatever this setting says.
limits.responseWriteMilliseconds5,000Time to write the finished picture to the caller. A caller that reads more slowly is dropped.
limits.responseChunkBytes32,768The answer is written in pieces of this size (4,096 to 65,536), so that a caller that stops reading is noticed. The most is 64 KB because a larger piece is taken whole by the operating system for a reader that reads nothing.
limits.maxRequestsInFlightPerClient1Requests one caller may have being served at the same time (1 to 64).
limits.maxConnectionsPerClient16Connections one caller may have open at the same time (1 to 256). Not counted for a proxy listed in network.trustedProxies.
limits.outputBudgetMegabytes128Memory for answers that are made and wait for their readers, on top of the memory budget below (1 to 4,096). It must hold the largest answer: the larger of limits.maxOutputBytes and limits.maxCommandsBytes.
limits.memoryBudgetMegabytes1,024Memory that the renders may use together. It decides how many labels are drawn at the same time. At the defaults that is 4 at a time; a request for the pictures of elements takes 2 of those places. One more is refused at once with BX6006 and never queued. A quarter of it is also the budget for the templates that are being received, each byte counted three times over; when that is full a request is refused with BX6018 before all of its template is read.

The limits of the label engine that are not in this table, such as the number of path segments, are fixed in the program at the values of The label engine for a demonstration page.

Who the caller is

The limits above are for a caller, and a caller is the address of the connection. An IPv4 address is one caller, and an IPv6 address is counted by its first 64 bits, because one subscriber usually holds a whole block of that size.

  • By default the address of the connection is used, and X-Forwarded-For is ignored. The header is a claim by whoever sent the request.
  • Behind a proxy, every caller connects from the proxy. Without help they all look like one caller, and the rule of one request at a time would let one of them through at a time. Set network.trustForwardedHeaders to true and list the proxy in network.trustedProxies.
  • Which proxy is trusted. Only a connection from an address in network.trustedProxies is believed. The service then reads X-Forwarded-For from its right end, for at most network.trustedProxyHops entries (1 to 8, 1 by default): starting with the address of the connection, while an address is one of your listed proxies, the entry to its left (the one that proxy added) is believed, and the caller is the last entry believed. With the default of 1 it is the last entry, the one that the proxy added itself. Set 2 when a listed front end is in front of a listed proxy, and so on, never more than the chain has: each hop beyond the first lets a visitor whose own address is inside a listed range choose the address it is counted as, once. If an address that is not listed is reached before the hops are used, it is the caller. The entries to the left of the caller were written by the caller and are ignored. A request from any other address keeps its own address, whatever its header says.
  • A quote in X-Forwarded-For. With network.edge.mode off, a visitor who sends X-Forwarded-For starting with a double quote is counted as the connection's own address (the proxy), because the step that reads the header takes the whole line as one quoted text. It adds at most one more allowance for that visitor, never a free choice of address, and the limit of all callers still holds. With network.edge.mode azureFrontDoor such a request is refused (403, BX6024).
  • Set the proxy up to add the address and not to pass the caller's header on as it is. The reference configurations in Deploying the label service do.

If you host the service

The page Deploying the label service says what to put in front of the service and gives a reference configuration for nginx and for Caddy. In short:

  • Put a web server with https in front of it, and let that server buffer the request and the answer. This is required before you let anyone you do not know reach the service. The service speaks only http, and it has its own limits, but a proxy that buffers is the only thing that keeps a slow caller away from it altogether.
  • Limit the connections for each address at the proxy.
  • Say who the caller is (the section above).
  • Keep a current .NET runtime.
  • Show the answers as text. The errors list holds ids and names that were written in the template. Insert every value into a page as text, never as markup, and show element ids in an isolated direction context. The service has already replaced control, direction and invisible characters with U+FFFD. See Diagnostic codes.
  • A web page that calls the service must not send cookies or credentials. List its web site in cors.allowedOrigins. The headers that the page can read are Retry-After, BarcoderX-Warnings, BarcoderX-Marked, BarcoderX-Image-Width, BarcoderX-Image-Height and Api-Supported-Versions.
  • Know what it does not do. It stores no template and no picture, writes no file, never fetches an address that a template names, and never redirects. Every picture and every set of commands carries the evaluation mark.

What is not built yet

  • The rest of the web API: stored templates, other output formats, printer languages other than ZPL and the printer's own text and barcode commands, print jobs, batch jobs, assets and the administration routes. See Web API.
  • An OpenAPI document and a documentation page generated from it.
  • A way to give the service a license. Until then, every picture and every set of commands carries the evaluation mark.
  • Several labels in one request, and data merged into a template.

BarcoderX is a product of P4 Software.

Was this page helpful?