Errors

API errors

Every error from an API operation has the same JSON shape:

{
  "code": "validation_failed",
  "correlation_id": "6f1c2a1e-4b7d-4c2e-9b3f-2d8e5a7c9f10",
  "retryable": false,
  "field_errors": [
    { "field": "expand", "code": "not_allowed" }
  ]
}

code is stable; build your error handling on it, not on the HTTP reason phrase.
retryable tells you whether the same request can succeed later.
field_errors lists the query parameters that were rejected (empty for other errors).
Include the correlation_id when you contact Simblia support.

HTTP	`code`	Meaning	What to do
401	`unauthenticated`	Missing, invalid or expired token, a token from the other environment, or a suspended or revoked client. The response has `WWW-Authenticate: Bearer error="invalid_token"`.	Get a new token. If that fails too, check the client in the Simblia app.
403	`forbidden`	The token lacks the scope the operation needs (`insufficient_scope`).	Ask for the scope when you get the token, or add it to the client.
422	`validation_failed`	A query parameter is unknown or invalid. Unknown parameters are always rejected.	Fix the request; see `field_errors`.
429	`rate_limited`	More than 600 requests per minute for this client.	Wait the number of seconds in `Retry-After`.
503	`dependency_unavailable`	A temporary problem on our side.	Retry with exponential backoff.

Treat any code you do not recognize like a non-retryable error unless retryable is true.

Token endpoint errors

POST /v1/oauth/token uses the standard OAuth 2.0 error format (RFC 6749, section 5.2) so that OAuth libraries understand it:

{ "error": "invalid_scope", "error_description": "The client does not have this scope." }

Possible error values: invalid_request, invalid_client, invalid_grant, unauthorized_client, unsupported_grant_type and invalid_scope. A wrong client ID or secret, a credential from the other environment and a suspended or revoked client all give 401 invalid_client. Rate limiting on the token endpoint uses the API error shape above (429 rate_limited).

See the API reference for the full schemas.