Errors
Error object
When something fails, the API returns an error object, either at the top level of the response (the whole call failed) or on an individual instance (that one value failed). The shape is the same in both cases.
{
"error": {
"code": "string",
"message": "string"
}
}| Field | Type | Description |
|---|---|---|
code | GUID | Stable identifier for the error. |
message | string | Human-readable description. |
Match on code, not message. Codes are stable GUIDs; messages are descriptive text that can change and may interpolate request values (for example, No rights context defined for Guid = '...').
{
"error": {
"code": "3f567979-e5b7-4725-8b93-9363ceaa5604",
"message": "Undefined Rights context"
}
}Two levels of error
Errors are reported at two levels.
A response-level error returns HTTP 400 with a top-level error body. The whole call was rejected; nothing was transformed.
An instance-level error returns HTTP 200 with one or more instances carrying an error object and a value of null. The remaining instances may still have succeeded, so always inspect both value and error per instance.
HTTP status codes
| Code | Meaning |
|---|---|
200 | Request processed. Inspect each instance for a per-instance error. |
400 | Request rejected: malformed body, missing required fields, unknown configuration, or an account/quota issue (see codes below). |
401 | Token missing, expired, or invalid. The response carries a WWW-Authenticate: Bearer error="invalid_token" header and no body. Re-authenticate. |
Response-level error codes
These reject the entire call with 400 Bad Request and a top-level error.
| Condition | message | code |
|---|---|---|
| Configuration not found or disabled | Configuration not found | df7817ea-b5b6-4933-b8da-ce28fff582e9 |
| Account not found | Account not found | 151a7cb0-9b13-494f-996c-0c7eee2bfd08 |
| Account suspended or disabled | Account status is not active | ecae14fc-b6fa-4e13-8ca3-cb85f21bd015 |
| Account balance has no credits | Account has no credits | 368b13a8-9cda-4a8e-b646-dd837f9f504e |
| Daily transformation limit exceeded | Daily transformation limit exceeded | 9ca42676-423a-4384-805a-0b671afecc4b |
| Monthly transformation limit exceeded | Monthly transformation limit exceeded | da593b4c-277e-440c-956e-3a6e7737b565 |
| Wrong request format or missing required field | Wrong request format | d60c07f8-acb0-4125-82fe-d3577d7eec98 |
| Request references no rights context | Request = '{request.Guid}' has no rights context definition | c0804f15-1632-4d54-8154-5b63f0ebbe1d |
| Referenced rights context has no evidence definitions | No rights context defined for Guid = '{request.RightsContext}' | c0804f15-1632-4d54-8154-5b63f0ebbe1d |
| Referenced processing context has no evidence definitions | No processing context defined for Guid = '{request.ProcessingContext}' | c0804f15-1632-4d54-8154-5b63f0ebbe1d |
Instance-level error codes
These return HTTP 200 with value: null on the affected instance. Other instances in the same call can still succeed.
| Condition | message | code |
|---|---|---|
| No processing context specified for the request | Processing context required | 118f797c-5f6f-4c46-a48f-4d1a9fb38f21 |
| Processing context GUID not returned by configuration | Undefined Processing context | 11b34d01-1425-489d-9665-2acd24e2922c |
| Processing context not present in the configuration | Processing context not found | 8d39bc4c-8698-4f7b-a4f8-ba74b593f86e |
| Processing context has no transformer sequence | Undefined Sequence | 978c46c6-5859-40e9-be71-bd9ca4badd1c |
| Referenced sequence not present in the configuration | Sequence not found | 3f63a7bc-39d9-4671-83a1-6f17595c0d03 |
| Sequence is missing the required extract transformer | Required transformer not found | 98f54c8f-d339-4b18-a524-90c53882be71 |
| Rights context GUID not returned by configuration | Undefined Rights context | 3f567979-e5b7-4725-8b93-9363ceaa5604 |
| Rights context not present in the configuration | Rights context not found | f800df3c-4288-4591-9b7b-64eff20ff9ed |
| Rights context has no rights assigned for the property | Undefined Rights context | 2f01b281-35eb-414b-85c2-b642ebde542f |
| No processing context specified to detect the transformation sequence | Processing context required | a81e9f99-b934-409c-b26d-78f2455a9ec7 |
Most instance-level errors point at a configuration mismatch between the GUIDs your request references and what the portal has provisioned. Check that the rightsContext and processingContext GUIDs in your request match contexts that exist, are enabled, and grant rights on the requested data instances.