Error codes

Biztraak uses different error formats at different API boundaries. Prefer the HTTP status, GraphQL errors array, and structured fields returned by the current endpoint. Error messages and codes can vary by authentication provider and workflow.

Common authentication errors

Token endpoints and OAuth/OIDC integrations may return standard OAuth-style errors such as:

• invalid_request: required parameters are missing or malformed.
• invalid_client or incorrect_client_credentials: client authentication failed.
• invalid_grant: the supplied authorization code, refresh token, or grant is invalid or expired.
• unauthorized_client: the client is not permitted to use the requested grant.
• invalid_scope: the requested scope is not available to the client.

These errors are not a substitute for the API’s HTTP status. A protected API operation generally reports missing or invalid bearer authentication as 401 Unauthorized and insufficient permissions as 403 Forbidden.

Validation and resource errors

REST endpoints commonly use 400 Bad Request with a ProblemDetails body for malformed input, 404 Not Found for missing or unauthorized resources, and 409 Conflict where a workflow or resource state prevents the requested change. The exact status depends on the controller and operation.

GraphQL validation and authorization failures are returned in the response’s errors array. A mutation can also return a domain payload with failure information while the transport request itself succeeds.

Client handling

1. Check the transport status.
2. Parse ProblemDetails for REST failures or errors for GraphQL failures.
3. Preserve a correlation or request identifier when the response provides one.
4. Do not retry authorization, validation, or not-found failures without changing the request or credentials.
5. For accepted asynchronous work, query the returned resource or workflow before retrying the mutation.

See API errors and responses, Authentication, and Authorization for the complete handling model.