A web page posts its JavaScript errors here, and a masked copy of the page beside the first one. The key is public: the Origin check and a per-address limit protect the endpoint.
Request
POST /api/v1/ingest/js/<js_key>
Origin: https://www.example.com
Content-Type: text/plain
The body is one report object or a JSON array of up to 10, at most 64 KB. text/plain keeps sendBeacon free of a CORS preflight; application/json works after one.
Example
curl
curl -X POST "https://codesafe.example/api/v1/ingest/js/$CODESAFE_JS_KEY" \
-H "Origin: https://www.example.com" \
-H "Content-Type: text/plain" \
-d '[{"message": "Uncaught TypeError: cart is undefined", "name": "TypeError",
"file": "https://www.example.com/assets/app.min.js", "line": 1, "col": 48211,
"url": "https://www.example.com/checkout"}]'JSON
[
{
"message": "Uncaught TypeError: cart is undefined",
"name": "TypeError",
"stack": "TypeError: cart is undefined\n at submitOrder (https://www.example.com/assets/app.min.js:1:48211)",
"file": "https://www.example.com/assets/app.min.js",
"line": 1,
"col": 48211,
"url": "https://www.example.com/checkout?step=2",
"priority": 3,
"count": 4,
"timestamp": 1793361900000,
"release": "2.14.1",
"environment": "production",
"tags": ["shop", "eu"],
"traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
"extra": {"userId": "1234", "snapshotId": "9f86d081884c7d65"}
}
]Fields
| Field | Type | Required | Limit | What it does |
|---|---|---|---|---|
message | string | no | ≤ 2,048 chars | The error's message |
name | string | no | ≤ 256 chars | The error class; Error when absent |
stack | string | no | ≤ 8,192 chars | The stack trace as text |
file | string | no | ≤ 512 chars | The URL of the script that threw |
line, col | integer | no | Where in that script; col lands in extra.col | |
url | string | no | a URL | The page: its host and path become the event's host and uri |
priority | integer | no | 0–7 | Syslog severity; 3 when absent |
count | integer | no | Repeats of this error in the page load; kept as extra.client_count | |
timestamp | number or string | no | epoch ms or s, ISO 8601 | When it happened |
release | string | no | ≤ 64 chars | The deploy label; it also picks the source map |
environment | string | no | ≤ 64 chars | The stage |
tags | array or string | no | ≤ 10 tags | Filterable tags |
traceId | string | no | ≤ 64 chars | The trace id that links the report to the server's error |
extra | object | no | 64 KB | Anything else; a few keys are read, see below |
codesafe reads these fields and ignores every other. The visitor's address, user agent and referer come from the request itself.
Snapshots
POST /api/v1/ingest/snapshot/<js_key>?id=<16 hex>&enc=gzip
Origin: https://www.example.com
Content-Type: application/octet-stream
The body is a masked copy of the page's HTML, raw or gzipped, at most 512 KB. The report names the same id in extra.snapshotId, and the event detail shows the page for 7 days.
| Parameter | Required | Limit | What it does |
|---|---|---|---|
id | yes | 16 lowercase hex | Chosen by the page; the first upload of an id wins |
enc | no | gzip | Says the body is gzip; any other value answers 400 |
codesafe stores a snapshot as it arrives: masking inputs and private text is the page's job before the upload.
Through your own server
A page can post its reports to its own domain and let your server forward them, so the browser talks to your origin only. Each forwarded report then comes from your server's address, so your server names the visitor:
POST /api/v1/ingest/js/<js_key>
Origin: https://www.example.com
Content-Type: text/plain
X-Codesafe-Key: <api_key>
X-Codesafe-Visitor-Ip: 203.0.113.7
| Header | What it carries |
|---|---|
X-Codesafe-Key | The project's secret api_key, the one its server senders use. Only your server sends it; a page never sees it |
X-Codesafe-Visitor-Ip | The visitor's address as your server resolved it from the connection: one IPv4 or IPv6 address, never a value the browser sent |
- With the project's
api_keyand a valid address, the report is stored under that address and counts against that address's 30 requests a minute.::ffff:203.0.113.7is read as203.0.113.7. - A forwarded report also counts against the project's budget for its
api_keyendpoints: 3,000 requests and 15,000 reports a minute, together with your server senders. Past it,429withRetry-After: 60. - A wrong key, or a value that is no single address, is ignored and never refused: the report counts as one from your server's own address.
- Forward the method, the body and
Content-Typebyte for byte, and the browser'sOrigin,User-AgentandReferer. TheOrigincheck, the first-party filter and the drop rules apply as to a direct report. - Pass codesafe's answer back unchanged: its status, its body and its
Access-Control-*headers. - The snapshot endpoint reads neither header. Forwarded snapshots all count against your server's 30 a minute, so post them straight to codesafe or leave them off.
The api_key already lets a server sender name the visitor of its own errors, so forwarding with it gives your server nothing new.
With your web server. A few lines of configuration forward the client script and the project's report endpoint, and nothing else of codesafe. Replace codesafe.example with your codesafe address and <js_key> with the project's key; keep the api_key in a file or variable outside your repository.
nginx
# the client script and this project's report endpoint, nothing else
location = /codesafe/js/codesafe-client.min.js {
proxy_pass https://codesafe.example/js/codesafe-client.min.js;
proxy_ssl_server_name on;
proxy_set_header Cookie "";
proxy_set_header Authorization "";
}
location = /codesafe/api/v1/ingest/js/<js_key> {
limit_except POST OPTIONS { deny all; }
proxy_pass https://codesafe.example/api/v1/ingest/js/<js_key>;
proxy_ssl_server_name on;
# holds the one line: proxy_set_header X-Codesafe-Key "<api_key>";
include /etc/nginx/codesafe-key.conf;
proxy_set_header X-Codesafe-Visitor-Ip $remote_addr;
proxy_set_header Cookie "";
proxy_set_header Authorization "";
proxy_connect_timeout 2s;
proxy_read_timeout 2s;
proxy_next_upstream off;
}Apache
# in the virtual host, not .htaccess: mod_proxy, mod_proxy_http, mod_headers, mod_ssl
SSLProxyEngine on
<Location "/codesafe/js/codesafe-client.min.js">
ProxyPass "https://codesafe.example/js/codesafe-client.min.js" timeout=2
RequestHeader unset Cookie
RequestHeader unset Authorization
</Location>
<Location "/codesafe/api/v1/ingest/js/<js_key>">
ProxyPass "https://codesafe.example/api/v1/ingest/js/<js_key>" timeout=2
<LimitExcept POST OPTIONS>
Require all denied
</LimitExcept>
# CODESAFE_API_KEY comes from a Define or the server's environment
RequestHeader set X-Codesafe-Key "${CODESAFE_API_KEY}"
RequestHeader set X-Codesafe-Visitor-Ip "expr=%{REMOTE_ADDR}"
RequestHeader unset Cookie
RequestHeader unset Authorization
</Location>The page then loads /codesafe/js/codesafe-client.min.js from your own domain and calls init({url: 'https://www.example.com/codesafe', key: '<js_key>'}).
- Forward these exact paths only. A whole
/codesafe/prefix would put codesafe's sign-in and console on your domain. - The visitor is the address your web server sees (
$remote_addr,REMOTE_ADDR). Behind a CDN or a load balancer, set up nginx'sreal_ipor Apache'smod_remoteipfirst, or every report names the balancer. proxy_set_headerandRequestHeader setreplace what the browser sent, so a visitor can neither pick an address nor send a key.
Responses
| Status | When | What the client does |
|---|---|---|
202 | Taken: a report answers {"success": true, "accepted": 1}, a snapshot {"success": true, "stored": true} | Nothing |
204 | The CORS preflight passed | Send the request |
400 | Malformed JSON, an empty batch or over 10 reports; a snapshot id, enc or body codesafe refuses | Fix the client; never retry |
403 | The Origin is not on ALLOWED ORIGINS, or browser reports are off | Fix the project's settings |
404 | Snapshots are off on this instance | Stop sending snapshots |
405 | The method is neither POST nor OPTIONS | Fix the client |
409 | The snapshot id is taken: {"success": true, "stored": false} | Drop it |
413 | Over 64 KB of reports, or 512 KB of snapshot | Send less |
429 | The address sent over 30 requests this minute, the project's day of snapshots is spent, or a forwarded report is past the project's budget | Drop it |
503 | codesafe cannot store it at the moment; Retry-After: 30 when it can say | Drop it, or retry once later |
Notes
js_keyis public. TheOriginheader must equal an allowed origin exactly,scheme://host[:port]:wwwand the bare domain are two origins.- A
403carries no CORS headers, so the page cannot read it; ACTIVITY counts every one with the origin it refused. - Every report is stored as
runtime: "browser",entry: "web"andkind: "error". - A dropped report still answers
202;accepteddoes not count it. - Reports and snapshots share the address's 30 requests a minute. No project budget applies: that limit holds a leaked key. Only a report your server forwards with the
api_keyalso counts against the project's budget.
What codesafe drops on arrival
- a report thrown by a browser extension or an in-app browser (
chrome-extension:,moz-extension:,safari-extension:,iabjs:,gsa:…), read offfileor the first frame ofstack, on every project; - with the project's FIRST-PARTY FILTER on, the default, a report thrown by a script on any host but an allowed origin, a listed first-party host or the page's own;
- a report less severe than the project's accept errors for priority ≤.
The extra keys codesafe reads
| Key | What it becomes |
|---|---|
userId, sessionId | the event's user and session |
snapshotId | the link to the snapshot uploaded with that id |
webdriver | true flags the event webdriver |
scriptsNotLoaded, scriptsFailed | a non-empty list flags it scripts_missing or scripts_failed |
tags | more tags for this event, joined with the top-level tags |
CORS
An allowed origin gets Access-Control-Allow-Origin with its own value, POST, OPTIONS as the methods, Content-Type as the only request header and a preflight cached for a day. A preflight from any other origin answers 403.
The snapshot budget
Each project takes 2,000 snapshots or 256 MiB of them a day, whichever comes first, from every address together. Past either, an upload answers 429 with Retry-After: 3600. A body that claims gzip and is none, or an empty body, answers 400.