Fixed header (4 bytes)
Version (2b), Type (2b), Token Length (4b), Code (8b), Message ID (16b). Always present, always this size.
Progress saves as you read. Mark sections complete as you go; your progress appears in the sidebar.
Related reference: CoAP message types.
A client asks for /sensors/temp, but a decoder reports only /sensors. To diagnose the mismatch, mark the bytes consumed by each field before interpreting the resource name.
Decode One Message Without Guessing Its Meaning
Start with the shorter request /temp. CoAP is the Constrained Application Protocol; this page uses its base UDP message format. UDP carries each message in a datagram, whose end bounds the bytes available to the parser. A payload is the application content carried after the message fields.
Read this illustrative request as hexadecimal bytes: 44 01 37 21 71 42 33 9A B4 74 65 6D 70. Count byte positions, or offsets, from zero. The fixed header occupies offsets 0–3. Split 44 into bits 01 / 00 / 0100: Version 1, Type 0 (Confirmable, abbreviated CON), and Token Length (TKL) 4. A Token matches a response to its request; it occupies offsets 4–7 here.
Byte 1, 01, is the Code for GET. Bytes 2–3, 37 21, are Message ID 0x3721, used for message acknowledgement and duplicate detection. Options are numbered fields after the Token. At offset 8, B4 splits into a high four-bit group, or nibble, B (11), and a low nibble 4. The first gives the increase from the previous option number, initially zero; the second gives the value length. Thus this is option 11, Uri-Path, with four value bytes: 74 65 6D 70 spells temp.
The value ends at offset 12, the datagram’s last byte. The request has no payload. You have accounted for all 13 bytes without searching for text or a delimiter. Later, apply the same counters to /sensors/temp and explain how a wrong length can swallow the next option header.
After this page, you should be able to:
CoAP Message Format introduces the fields. Here, use two counters to decode them: the next byte offset and the previous option number.
The sequence is fixed header, Token, options, then a payload marker and nonempty payload if present. This page stays within base RFC 7252 CoAP over UDP. RFC 8974’s extended-token form and RFC 8323’s TCP framing require different rules.
If a server returns 4.02 Bad Option, inspect the encoded options before deciding which fault caused it. An error code alone does not show where the sender’s and receiver’s interpretations diverged.
Generalize the request you just decoded. The four-byte header contains Version (2 bits), Type (2 bits), TKL (4 bits), Code (8 bits), and Message ID (16 bits). Type values are 0 Confirmable (CON), 1 Non-confirmable (NON), 2 Acknowledgement (ACK), and 3 Reset (RST). In the base format, TKL is 0–8; check that many Token bytes are available before looking for options.
Split Code into a 3-bit class and a 5-bit detail, written class.detail. For example, 0x45 is decimal 69: class 2 and detail 5, or 2.05 Content. The request codes 0.01, 0.02, 0.03, and 0.04 mean GET, POST, PUT, and DELETE. Code 0.00 means Empty, so class zero alone does not establish a request. Response classes 2, 4, and 5 denote success, client error, and server error; examples are 2.05 Content, 4.04 Not Found, and 5.00 Internal Server Error.
For the running request, the first option offset is 4 + TKL = 8. A decoder that starts at offset 4 would read Token byte 71 as an option prefix. Recognizable path text cannot repair that earlier boundary mistake.
Keep the byte offset separate from the option number. Reading an option value advances the offset; decoding its delta advances the option number. Neither counter can replace the other.
Use the figure in the parent chapter to locate the fixed fields and the variable fields that follow them.
In the figure in the parent chapter, read Version, Type and TKL in byte zero, then Code and Message ID. After the Token, consume each option’s declared length. Recognize 0xFF as a payload marker only where the next option prefix could begin; the same byte inside a declared Token or option value remains part of that field.
Version (2b), Type (2b), Token Length (4b), Code (8b), Message ID (16b). Always present, always this size.
Length equals TKL. Correlates a response with its request, independent of the Message ID.
Numbered type-length-value fields: the type identifies the option, length counts its value bytes, and value carries its content. The type is encoded as a delta from the preceding number.
At an option boundary, 0xFF starts a nonempty payload. Without a marker, remaining bytes must parse as options; a marker alone is malformed.
In the running request, B4 represents option number 0 + 11 = 11 and value length 4. This is a type-length-value (TLV) field: its type is Uri-Path, its length is four bytes, and its value is temp. Each later option encodes the increase from the previous option number. Equal numbers are allowed: another Uri-Path uses delta zero.
The prefix has a delta nibble followed by a length nibble. Values 0–12 are literal. Nibble 13 means add 13 to the next one-byte unsigned value; nibble 14 means add 269 to the next two-byte unsigned value, most significant byte first. Consume the delta extension first, then the length extension, then exactly the declared value bytes. If either nibble is 15, it cannot encode an option; the full byte FF at an option boundary is instead the payload marker.
For a synthetic extension example, let the previous option number be zero and read D1 02 AA. Prefix D1 gives delta indicator 13 and length 1. Extension 02 makes the delta 13 + 2 = 15, so the option number is 15. Only AA is the value. This demonstrates field boundaries, not a usable query value. If the extension or declared value bytes are missing, stop: the encoding is incomplete.
Uri-Path (11) repeats for each path segment; /sensors/temp has values sensors and temp. Uri-Query (15) repeats for query parameters. Content-Format (12) identifies the payload's media type with a number rather than a text media-type name.
The parity of the option number decides how an unknown option is treated. Odd numbers are Critical: a server that does not understand a critical option in a request must reject it with 4.02 Bad Option. Even numbers are Elective: an unrecognized elective option is ignored. So Uri-Path (11, odd) is critical, while Content-Format (12, even) is elective.
Start with previous option number zero. At each option boundary, check for FF; otherwise decode delta, length, and value in that order. Add the delta to the previous number and record the next offset. Option numbers are nondecreasing, so delta zero preserves a repeated option. Check recognition only after locating the field correctly. For a server processing a request, an unknown critical option requires 4.02 Bad Option; that response alone does not identify the offending byte.
Return to 44 01 37 21 71 42 33 9A B4 74 65 6D 70. The table checks the running request against the general rules. Mark each field before reading the response.
Keep two counters while decoding: the byte offset in the UDP payload and the previous option number. The fixed header consumes offsets 0 through 3. TKL says the next four bytes are Token, so Options begin at offset 8. The first option byte is then decoded as a delta from previous option number 0. That is why 0xB4 means delta 11 and length 4: option number 11 is Uri-Path, and the next four bytes spell temp.
The server answers by piggybacking the response on the ACK. The reply begins 0x64 (Version 1, Type 2 = ACK, TKL 4), then Code 0x45 which decodes as 2.05 Content, then the same Message ID 0x3721 and the same 4-byte Token. For a text/plain reading, Content-Format 0 can be encoded as C0: delta 12 from zero and a zero-length integer value representing zero. The complete illustrative reply is 64 45 37 21 71 42 33 9A C0 FF 32 32 2E 35. Marker FF is at offset 9; offsets 10–13 contain the ASCII text "22.5".
The payload marker is not optional once payload bytes exist. Without 0xFF, the remaining bytes must be decoded as options or rejected if malformed; the parser cannot guess that 32 starts a text reading. A marker with no following payload is also malformed. With the marker present, anything after it is application payload and is interpreted using Content-Format. In a trace review, mark the header, Token, each option, marker, and payload boundaries before arguing about application behavior.
Notice the two correlations at work. The ACK echoes the Message ID 0x3721 to confirm receipt at the messaging layer, and it echoes the Token to bind the answer to the request at the request/response layer. Both are visible directly in the bytes.
Transfer the same method to this illustrative request: 41 01 12 34 A1 B7 73 65 6E 73 6F 72 73 04 74 65 6D 70. It is a Confirmable GET with one-byte Token A1 and Message ID 0x1234. Its first byte is 0x41: Version 1, Type 0 and Token Length 1. The Code byte is 0x01. The two Message ID bytes follow, then the Token. The options therefore begin after 4 header bytes plus 1 Token byte, at offset 5 when counting from zero.
Uri-Path has option number 11. Encode the first segment sensors as seven text bytes. Relative to the initial option number zero, the delta is 11 and the length is 7, so its option header is 0xB7. The next segment temp uses the same option number: the delta is zero, its length is 4, and its header is 0x04. The slash separates URI segments in a human-readable address; it is not a value byte between these two encoded options.
Count the entire request before adding transport overhead. It has 4 fixed bytes, 1 Token byte, an 8-byte first option and a 5-byte second option. The total is 4 + 1 + 8 + 5 = 18 bytes. There is no request payload here, so there is no payload marker. This count excludes UDP, IP and any security wrapper.
Use the figure in the parent chapter to check the offsets: fixed header first, Token next, then the variable options. The diagram’s payload marker becomes relevant only if a payload follows. A decoder that assumes every request contains a marker will fail on this valid empty-body GET.
Before changing anything, predict the second option’s prefix offset. The first prefix is at offset 5 and its seven value bytes occupy offsets 6–12; the next prefix is 04 at offset 13. Its four value bytes occupy offsets 14–17.
Now replace B7 with B8. The decoder consumes offset 13’s 04 as the eighth byte of the first path value. It then tries to interpret 74 at offset 14 as another option prefix. The first wrong boundary is already visible at offset 13; recognizing the letters temp is no reason to repair it silently. A shifted stream may fail later or decode into unintended options, so a missing segment alone does not prove which check failed.
For a distinct truncation case, stop a datagram after its four-byte header while TKL still says one. There is no Token byte available, so reject it before processing options. Simply removing a byte from a longer stream need not expose Token truncation: the next available byte would instead be consumed as Token. Diagnose the bytes actually present, not the sender’s intended fields.
Use the same rule for each trace: calculate the next offset, check bytes available, and only then interpret the value.
A base CoAP message has TKL=3 and a complete Token. At which zero-based offset do options begin?
Offset 7
Correct. Four header bytes plus three Token bytes gives offset 7.
A server decodes D0 02 at an option boundary with previous option number zero. It does not recognize the resulting option. What should it do with this otherwise valid request?
Reject with 4.02 Bad Option: the decoded number is 15, which is critical.
Correct. Delta = 13 + 2 = 15, added to previous number zero. Odd number 15 is critical, so an unrecognized option requires rejection.
A CoAP server receives an otherwise valid request with an unrecognised option numbered 10. How should it handle this unknown option?
Ignore the elective option and process the request
Correct. Option 10 is even, hence elective; an unknown elective option is ignored.
A CoAP message begins with byte 0x54. What does that byte encode?
Version 1, NON type, and Token Length 4.
Correct. Bits 01 01 0100 encode version, type, and token length.
In sorted CoAP option order, Uri-Host (option 3) is followed by the first Uri-Path (option 11). What option delta encodes that Uri-Path?
Delta 8
Correct. Option delta is current minus previous option number: 11 - 3 = 8.
Before signing off a CoAP parser or trace review, verify that:
4.02 Bad Option; it ignores unrecognized elective options.0xFF starts a nonempty payload. An 0xFF inside a declared field is data, and a marker without payload is malformed.Review the message fields first. Then see how they support a reliable exchange.

Chapter
CoAP Message Format
Return to the main message-format chapter and worked size comparisons.

Chapter
CoAP Message Reliability and Exchange Contracts
Connect Message ID and Token parsing to CON/NON/ACK/RST exchange behavior.

Chapter
CoAP Resource Contract and Negotiation Design
Apply Content-Format, Accept, ETag, Max-Age, and Uri-Path options to API contracts.

Chapter
CoAP Block Transfer and Discovery Contracts
Extend option parsing to block-wise transfer and discovery metadata.

Chapter
CoAP Implementation Stack Trace Contracts
Check how libraries expose parsed headers, options, payloads, and trace evidence.
After wire-format parsing is reliable, continue with CoAP Message Reliability and Exchange Contracts to see how those bytes drive retransmission, ACK matching, duplicate detection, and separate responses.

Knowledge check · self-test
__IOT_RELATED_TITLE__
__IOT_RELATED_DESCRIPTION__