Parse Error Stack¶
POST /api/v1/rum_sourcemap/parse_stack
Overview¶
Use the corresponding SourceMap to restore the RUM error stack.
Before Calling and Usage Steps¶
The current key requires rum.Query. The management permission rum.rumCfgManage cannot replace this query permission. Only the Workspace to which the current key belongs is supported. Take appId from content[].appId in the RUM Application Summary; it must be consistent with the app_id in the SDK/error record and cannot be replaced by the internal database UUID. SourceMap is precisely located by application, environment env, and version version; case/whitespace are part of the identifier itself and must exactly match the collection record. Omitting env/version or using an empty string indicates an empty environment/version, not a wildcard for all. The current managed lifecycle requires each to be at most 256 characters.
You must POST an application/json request body; query-encoded body parameters are not allowed, and real stack traces must not be placed in the URL. First upload the corresponding build artifact and confirm that the version is readable, then pass the original error_stack, env, version, error_type, and os; this endpoint does not write comments or update Error Tracking status.
Web currently parses the SDK-standardized “at function @ URL:line:column” format. It matches .js.map in the same directory by URL path; for example, it matches static/js/app.js.map. It is recommended that the map contain sourcesContent to return source context; the source JS can assist function name inference. When os is Android/iOS and error_type=reactnative/reactnative_crash, RN uses the js/ subdirectory and supports common Hermes/Metro addresses; RN native ios_crash/anr_error uses ios/, Android java_crash/anr_error uses android/mapping.txt, and native_crash/anr_crash uses the ABI symbol directory under android/.
For native iOS applications, only ios_crash/anr_error are handled and must match the build dSYM; Android java_crash/anr_error/network_error uses mapping.txt, and native_crash/anr_crash matches the symbol directory by ABI/ABI list. Applications with miniapp/custom/harmonyos or unknown error_type/os currently have no equivalent branch; the response may return js with an empty stacktrace, and this 200 must not be taken as support for that platform.
js is a frame array, and native is text. When a frame does not match a map/source/mapping, the original line and column may be retained without an error; native output may also be partially symbolized or fall back to the original text. Check whether filename/function/context_line match the expected source file; HTTP 200 or a non-empty result does not guarantee that every frame has been restored. The response may contain source code snippets and is intended only for authorized callers. Success responses include Cache-Control:no-store; error responses are not guaranteed to include the same header.
Request Headers¶
| Parameter Name | Type | Required | Description |
|---|---|---|---|
| DF-API-KEY | string | Y | OpenAPI authentication credential for the Workspace. Example: <DF-API-KEY>How to obtain or fill in: Obtain an OpenAPI Key with this operation permission from API Key Management in the target Workspace. |
Body Request Parameters¶
| Parameter Name | Type | Required | Description |
|---|---|---|---|
| appId | string | Y | Required active application identifier in the current Workspace; it is not the internal RumCfg UUID and cannot be used across Workspaces. Allow null: False Example: payment_webHow to obtain or fill in: Obtain from content[].appId in the RUM Application Summary or app_id in the error record. |
| env | string | Optional string, defaults to empty environment, maximum 256 characters; it does not represent all environments, and null is not allowed. Allow empty string: True Allow null: False Example: productionHow to obtain or fill in: Obtain from the client release environment/error record env, exactly matching the upload. |
|
| error_type | string | Web can usually omit it. iOS supports ios_crash/anr_error; Android supports java_crash/anr_error, native_crash/anr_crash, and network_error; RN uses os in combination to determine the js or native branch. This is currently not a declared enum; unknown values are not guaranteed to be rejected and may also return an empty JS result.Allow empty string: True Allow null: False Example: reactnativeHow to obtain or fill in: Obtain from error_type in the error record. |
|
| os | string | Optional string; RN requires Android or iOS, and case is ignored internally. For other types, the platform is usually determined by the application's jsonContent.type; this field does not modify the application platform.Allow empty string: True Allow null: False Example: AndroidHow to obtain or fill in: Obtain from the operating system field in the error record; this is especially required for RN. |
|
| stack | string | Y | Required non-blank string, maximum 131072 characters and 2000 lines; newlines in JSON must be properly escaped. Web currently recognizes the SDK-standardized at function @ URL:line:column format; non-normalized plain V8/Chrome text may return 406, so do not assume any text can be parsed.Allow null: False Example: "Error: example\n at say @ https://cdn.example.com/static/js/app.js:1:1"How to obtain or fill in: Prefer to obtain it verbatim from error_stack in the actual RUM error record, without rewriting line or column numbers yourself. |
| version | string | Optional string, defaults to empty version, maximum 256 characters; it does not represent the latest/all versions, and null is not allowed. Allow empty string: True Allow null: False Example: 1.2.3How to obtain or fill in: Obtain from the actual client release version/error record version, corresponding to the build artifact. |
Additional Parameter Notes¶
Use a Workspace API Key with the “RUM Data Query” permission. The target RUM application must belong to that Workspace.
Take app_id from the RUM error record as appId, and error_stack as stack, and pass the record's env and version.
When the environment or version is omitted, matching uses an unspecified value; the system looks up the mapping according to the environment and version corresponding to the request.
For React Native calls, also pass os and error_type from the record. reactnative and reactnative_crash on Android and iOS use the JavaScript branch; native crashes use the native parsing branch for the corresponding platform.
When the corresponding SourceMap is readable, if React Native is missing these two fields or the combination is unsupported, it returns the same empty result as the console: {"stackType":"js","stacktrace":[]}.
- When
content.stackTypeisjs,content.stacktraceis an array of stack frames. A successful response may retain unmapped original frames; source context fields are returned when the corresponding mapping provides source code. - When
content.stackTypeisnative,content.stacktraceis non-empty native stack trace text and may retain un-restored frames. For example{"stackType":"native","stacktrace":"java.lang.IllegalStateException\n at com.example.Checkout.submit(Checkout.java:42)"}. - Parameters are passed in the JSON request body; the URL query parameter
bodyis prohibited.appIdandstackmust contain non-whitespace content. - Submit one original stack trace per request.
stackhas a maximum of 131072 characters and 2000 lines; exceeding the limit returns HTTP 400ft.SourceMapStackTooLong. Calls are also subject to Workspace OpenAPI rate limits and existing SourceMap read limits. - Common authentication errors include
ft.APIAkKeyFailed(missing API Key),ft.InvalidAPIKey(invalid API Key),ft.APIKeyDisabled(API Key disabled), andft.Forbidden(insufficient permissions). - Missing required fields or incorrect parameter types return HTTP 406
ft.ParameterValidationFailed. A required value that is blank returns HTTP 400ft.SourceMapRequiredFieldBlank. A non-JSON request or passing the URL query parameterbodyreturns HTTP 400ft.SourceMapJsonBodyRequired. A JSON syntax error returns HTTP 400ft.RequestJsonFormatError; when the JSON top level is not an object, it returns HTTP 400ft.JsonFormatError. UseAccept-Languageto select the error message language. - Parsing errors include
ft.NotFoundRumSet(application not found in the Workspace),ft.SourceMapPackageNotFound(corresponding package not found),ft.SourceMapFileInvalid(invalid mapping file),ft.SourceMapStackFormatInvalid(unrecognized stack format),ft.SourceMapNativeSymbolFileNotFound(missing Android Java mapping file), andft.SourceMapNativeParseFailed(native parsing produced no usable text).
Request Example¶
curl --request POST 'https://openapi.guance.com/api/v1/rum_sourcemap/parse_stack' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"appId":"payment_web","env":"production","version":"1.2.3","stack":"Error: example\n at say @ https://cdn.example.com/static/js/app.js:1:1"}'
Response¶
HTTP 200, application/json. The example below shows the main fields that can be read directly.
| Field | Type | Description |
|---|---|---|
| content.stackType | string | js or native, used to determine the JSON type of stacktrace. |
| content.stacktrace | array<object> or string |
An array of frame objects when js, or symbolized text when native; JS frames that are not matched may still return original positions, and an empty array does not mean parsing succeeded. |
| content.stacktrace[] | object | A single JS frame; fields with no value may be omitted. |
| content.stacktrace[].name | string | SourceMap token name; may be omitted and does not necessarily equal the function name. |
| content.stacktrace[].function | string | Function name; may be an input or inferred value. |
| content.stacktrace[].source_url | string | Relative URL path of the matched map; typically the URL with the leading / removed and .map appended; may be omitted when there is no value. |
| content.stacktrace[].filename | string | Restored source file name or the un-restored position, not the server physical path. |
| content.stacktrace[].path | string | Original stack path. |
| content.stacktrace[].platform | string | Optional platform marker. |
| content.stacktrace[].stack_line | string | Original stack line from the input. |
| content.stacktrace[].lineno | integer | 1-based source line number when restoration succeeds; the original position may be retained when unmapped. |
| content.stacktrace[].colno | integer | 1-based source column number when restoration succeeds. |
| content.stacktrace[].context_line | array | Optional two-element array [source line number, line text]; omitted when there is no context. |
| content.stacktrace[].context_line[0] | integer | 1-based source line number. |
| content.stacktrace[].context_line[1] | string | Source line text. |
| content.stacktrace[].pre_context | array | Array of preceding lines, each item [1-based line number, text], up to about 5 lines, may be []. |
| content.stacktrace[].pre_context[] | array | Two-element array [source line number, text]. |
| content.stacktrace[].pre_context[][0] | integer | Source line number. |
| content.stacktrace[].pre_context[][1] | string | Source text of that line. |
| content.stacktrace[].post_context | array | Array of following lines, each item [1-based line number, text], up to about 5 lines, may be []. |
| content.stacktrace[].post_context[] | array | Two-element array [source line number, text]. |
| content.stacktrace[].post_context[][0] | integer | Source line number. |
| content.stacktrace[].post_context[][1] | string | Source text of that line. |
| content.declaration | object | Common declaration for the current Workspace; frames are not recursively inserted. |
| content.reasonCode | string | Error response only: machine-readable reason, e.g. active_operation/invalid_scope/registry_missing. |
| content.action | string | Error response only: suggested action, e.g. retry_after_operation/verify_ownership/check_scope_and_upload. |
| content.retryable | boolean | Error response only: server-suggested retryable flag; cannot be used alone to replay an already-published write. |
| content.uploadCommitted | boolean | Only for some single-file error diagnostics: true means the write has been confirmed published; omission does not equal false or confirm that the write was not committed. |
| content.actualBytes | integer | Only for some capacity errors: number of bytes counted. |
| content.maxBytes | integer | Capacity/read limit in bytes. |
| content.workspaceUUID | string | Some restricted error diagnostics: current Workspace UUID. |
| content.appId | string | Some restricted error diagnostics: public application identifier. |
| content.rumCfgUUID | string | Some restricted error diagnostics: internal application identifier, used only for support troubleshooting and does not replace the request appId. |
| content.env | string | Some error diagnostics: environment. |
| content.version | string | Some error diagnostics: version. |
| content.bundleUUID | string | Some error diagnostics: generation record ID for this request, not uploadId. |
| content.state | string | Some error diagnostics: generation state. |
| content.resource | string | Some occupancy diagnostics: resource type, e.g. application/bundle. |
| content.shared | boolean | Some occupancy diagnostics: whether access is shared. |
| content.waitedSeconds | number | Some occupancy diagnostics: seconds already waited. |
| content.waitSeconds | number | Some occupancy diagnostics: allowed wait in seconds. |
| content.waitExhausted | boolean | Some occupancy diagnostics: this wait was exhausted. |
| content.elapsedSeconds | number | Some single-file error diagnostics: operation duration in seconds. |
| content.phase | string | Some error diagnostics: failure phase. |
| content.phaseElapsedSeconds | number | Some error diagnostics: phase duration in seconds. |
{
"code": 200,
"content": {
"stackType": "js",
"stacktrace": [
{
"function": "say",
"source_url": "static/js/app.js.map",
"filename": "app.ts",
"path": "/static/js/app.js",
"stack_line": " at say @ https://cdn.example.com/static/js/app.js:1:1",
"lineno": 1,
"colno": 1,
"context_line": [
1,
"console.log(1);"
],
"pre_context": [],
"post_context": []
}
],
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
{
"code": 200,
"content": {
"stackType": "native",
"stacktrace": "java.lang.RuntimeException: example\n at com.example.Payment.run(Payment.java:10)",
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
Error Response¶
For authentication, rate limiting, and common request errors, see Common Error Definitions.
Storage lifecycle retains compatibility error codes: 409 is usually still ft.InvalidAction; the localized message and content.reasonCode further distinguish the cause. Do not treat message names such as SourceMapOperationBusy as the guaranteed errorCode. During reads, missing package/processing/unavailable is usually 404 ft.SourceMapPackageNotFound; see reasonCode for the specific cause. Back off and retry only when retryable=true is explicitly returned and the current state allows it; when uploadCommitted=true, do not replay a write that has been confirmed published. SourceMapNativeParseFailed explicitly passes through 500; other internal parsing exceptions not passed through uniformly return 500 ft.InternalServerError. Not every frame with a missing map triggers 404.
| HTTP Status | errorCode | Trigger Condition | Message or Response Description | Handling |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | Request field is missing, or the field value violates declared validation conditions | Parameter parsing failed | Check the parameter location, field name, type, and value. |
| 400 | ft.RequestJsonFormatError | Request JSON syntax is invalid | Request JSON format error | Correct the JSON according to content.reason, line, and column. |
| 400 | ft.JsonFormatError | JSON top level is not an object | Some JSON file format error | Submit a JSON object. |
| 400 | ft.SourceMapJsonBodyRequired | Not an application/json request body, or a body parameter exists in the URL | Pass parameters in the JSON request body; do not use the URL query parameter body. | Switch to POST JSON and remove the URL body parameter. |
| 400 | ft.SourceMapRequiredFieldBlank | appId or stack contains only whitespace | stack must contain non-whitespace content. | Enter non-empty actual values. |
| 400 | ft.SourceMapStackTooLong | stack exceeds 131072 characters or splitlines exceeds 2000 lines | stack can contain at most 131072 characters and 2000 lines. | Reduce the stack in this request and keep the portion to be parsed. |
| 404 | ft.NotFoundRumSet | Application is not in the current Workspace, has been deleted, or does not exist | Specified RUM setting not found | Refresh the RUM Application Summary and use the real appId in the current Workspace. |
| 404 | ft.SourceMapPackageNotFound | No record for the selected environment/version, processing, unavailable, or required file missing | Return localized prompts such as record not found/still processing/unreadable/source file does not exist according to reasonCode | Check appId/env/version and version status; wait for bundle_processing; for source_files_missing, ask the administrator to check the files or upload again. |
| 409 | ft.InvalidAction | Upload/read/cleanup conflict, legacy directory takeover not completed, ownership/recovery pending verification, or environment/version outside the lifecycle allowed range | Return a specific localized prompt according to reasonCode, e.g. the SourceMap is being used by another upload, read, or cleanup operation | Read content.reasonCode/action/retryable: for active_operation/active_upload, etc., back off as instructed; for owner_recovery_required/ownership_verification_required/legacy_invalid, ask the administrator to verify first, and do not delete the occupancy record or force overwrite on your own. For invalid_scope, check that env/version are at most 256 characters. |
| 406 | ft.InvalidFileName | File relative path, symbolic link, or historical release path is unsafe | The SourceMap file path does not meet requirements or contains an unsupported link. Check the relative path and directory structure of the uploaded file. | Use a valid relative path within the package, without .., backslashes, absolute paths, or symbolic links; check reasonCode=invalid_path. |
| 413 | ft.SourceMapSnapshotTooLarge | File snapshot required for reading exceeds the site limit, default 2 GiB | The total size of files required for this SourceMap read exceeds the limit | Reduce the number of version files or ask the administrator to check the limit. |
| 406 | ft.SourceMapStackFormatInvalid | Web/RN text cannot be recognized as a usable stack frame | Unable to recognize the SourceMap stack format | Use the RUM-standardized error_stack and check the application platform and language branch. |
| 406 | ft.SourceMapFileInvalid | The actually matched map or auxiliary source cannot be read/parsed | SourceMap file content is invalid or cannot be parsed | Check the build version, map format, and encoding; do not upload arbitrary JSON renamed to .map. |
| 404 | ft.SourceMapNativeSymbolFileNotFound | The strict Android Java branch is missing mapping.txt | Symbol file required for native stack parsing was not found | Upload the mapping.txt for the corresponding build; for RN, place it under android/. |
| 500 | ft.SourceMapNativeParseFailed | The strict Android symbol tool failed/has no valid output, or the native branch ultimately has no non-empty text | Native stack parsing failed | Keep the traceId and ask the administrator to check the symbol tool and build files; this 500 is explicitly passed through. |
| 500 | ft.InternalServerError | Database, file read/snapshot, historical configuration, or unhandled parsing exception | Internal error | Keep the traceId and application/env/version, first confirm the version status and files, then handle according to the actual error; reads can be retried with backoff. |