Errors and problem codes

API errors use RFC 9457 Problem Details with the application/problem+json media type. Use the stable, machine-readable code field in application logic. The detail field contains human-readable context.

{
  "type": "https://docs.portfolio.exchange/external-api/v1/problems/authentication-failed",
  "title": "Authentication failed",
  "status": 401,
  "detail": "Valid authentication is required.",
  "instance": "urn:uuid:b495f901-5456-4df6-a4da-cc750638c66b",
  "code": "authentication-failed",
  "requestId": "b495f901-5456-4df6-a4da-cc750638c66b",
  "violations": null
}

Preserve X-Request-Id when contacting support. If you send a valid X-Correlation-Id, the API echoes it for your own tracing.

Requests that reach the API receive a new X-Request-Id. This includes authentication failures and empty 404 responses when the API is disabled or the requested major is unsupported. Those 404 responses have no Problem Details body. The API echoes a valid X-Correlation-Id and omits an invalid one. API Gateway errors may use another response format.

X-Correlation-Id is optional and must contain exactly one value of 1–64 visible ASCII characters, without spaces or control characters. Use an opaque diagnostic identifier, such as a randomly generated UUID. You may reuse it to group related attempts; it does not provide authentication, authorization, or idempotency.

Valid correlation values are logged unchanged and may also be stored in audit records. Do not put names, email addresses, account details, financial information, access tokens, passwords, or other secrets in this header. Format validation does not detect sensitive content or mask it for you.

Problem catalogue

The type URI remains a stable identifier and opens the matching entry below. Match the code, rather than the human-readable detail, in your integration.

Code	HTTP status	Meaning	Recommended client action
`invalid-request`	400	The request has malformed syntax or invalid headers or query parameters.	Correct the request using the endpoint reference before retrying.
`invalid-cursor`	400	The cursor is invalid, expired, modified or belongs to another request context.	Start a new traversal without a cursor.
`invalid-correlation-id`	400	`X-Correlation-Id` is not exactly one visible ASCII value of 1–64 characters.	Send a single valid value or omit this optional header.
`authentication-failed`	401	Valid Bearer authentication is required.	Obtain or refresh your token using the onboarding instructions, then retry.
`access-denied`	403	Your authenticated identity cannot perform this request.	Check your access rights with your onboarding contact before retrying.
`not-found`	404	The resource is absent or not visible to your Profile.	Check the versioned path and resource identifier, then use discovery to select an accessible resource.
`method-not-allowed`	405	The HTTP method is unsupported for this path.	Use a method listed in the `Allow` response header.
`not-acceptable`	406	The `Accept` header does not allow `application/json`.	Request `application/json`.
`conflict`	409	The request conflicts with the current resource state.	Read the detail and refresh the resource before deciding whether to retry.
`unsupported-media-type`	415	The request body uses an unsupported media type.	Use the `Content-Type` documented for this operation.
`validation-failed`	422	One or more request values are invalid.	Inspect violations for the JSON Pointer, code and detail; correct those values before retrying.
`internal-error`	500	An unexpected server error occurred.	Keep `X-Request-Id` for support. Retry only when the operation is safe to repeat.
`service-unavailable`	503	The service is temporarily unable to complete the request.	For operations safe to repeat, use bounded retries with exponential backoff and jitter.

Problem catalogue​

Problem catalogue