Skip to content

feat(upload): Table of common error codes #20072

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jjbayer merged 2 commits into from
Oct 19, 2026
Merged

feat(upload): Table of common error codes #20072

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3b9fd20
feat(upload): Table of common error codes
jjbayer Oct 19, 2026
6e51000
wording
jjbayer Oct 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 17 additions & 1 deletion develop-docs/sdk/telemetry/attachments/upload.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -114,6 +114,22 @@ This allows the client to upload attachments that are much larger than what the

SDKs **MUST** use this location to attach a [placeholder item](/sdk/telemetry/attachments/#attachment-placeholders) to the event envelope. SDKs **MUST NOT** use the `Location` header from the initial `POST` request, or any intermediate request, because it may not contain all the fields needed to create a valid placeholder.

## Common Error Responses

This table lists some of the errors you might encounter while uploading.

| Status | Error Text | Solution |
| ----------------------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| 400 Bad Request | `Missing X-Decoded-Content-Length header` | Specify the size of the request body before compression. |
| 400 Bad Request | `non-final chunk {chunk_length} is smaller than upload granularity {upload_granularity}` | Use chunks of at least `Upload-Min-Chunk-Size` bytes, in multiples of `Upload-Chunk-Granularity`, except for the final chunk. |
| 409 Conflict | `upload offset mismatch (server holds {offset} bytes)` | Make a `HEAD` request to obtain the server's current state. |
| 413 Payload Too Large | `Chunk of {chunk_length} bytes exceeds the remaining {remaining} bytes` | You are trying to upload more than you initially declared with `Upload-Length`. Cap the file or look for bugs in the counting logic. |
| 413 Payload Too Large | `length limit exceeded` | The request's `Content-Length` exceeds the server's request body size limit. Send smaller chunks. |
| 413 Payload Too Large | _empty response_ | Split your file into smaller chunks. |
| 501 Not Implemented | `upload error: resumable upload declined` | Send the attachment in an envelope instead, or drop it if it is too large. |
| 503 Service Unavailable | | Retry. |
| 504 Gateway Timeout | | Retry. |

## Compression

The byte sizes in the headers refer to the request body _before_ compression, that is, before applying `Content-Encoding`. This applies to `Upload-Chunk-Granularity`, `Upload-Min-Chunk-Size`, `Upload-Max-Chunk-Size` and `Upload-Offset`. The server interprets `Content-Encoding` on a `PATCH` request as a self-contained transport optimization that only concerns the current request in isolation, not the full upload.
The byte sizes in the headers refer to the request body _before_ compression, that is, before applying any form of `Content-Encoding`. This applies to `Upload-Chunk-Granularity`, `Upload-Min-Chunk-Size`, `Upload-Max-Chunk-Size` and `Upload-Offset`. The server interprets `Content-Encoding` on a `PATCH` request as a self-contained transport optimization that only concerns the current request in isolation, not the full upload.
Loading