Error Handling

SutraID uses standard HTTP status codes and returns structured JSON error responses. All errors follow a consistent format.

Error Response Format

{
  "statusCode": 401,
  "message": "Invalid or expired token",
  "error": "Unauthorized"
}

Validation errors (400) include an array of specific field errors:

{
  "statusCode": 400,
  "message": [
    "email must be an email",
    "password must be longer than or equal to 8 characters"
  ],
  "error": "Bad Request"
}

HTTP Status Codes

Code	Title	Description	Resolution
`400`	Bad Request	The request body failed validation. Check required fields and data types.	Review the request body against the API reference. Ensure all required fields are present and correctly typed.
`401`	Unauthorized	Missing, invalid, or expired authentication token.	Include a valid access token in the Authorization header. If expired, obtain a new token using your refresh token.
`403`	Forbidden	The authenticated user lacks permission for this action.	Check the user's organization role. The required permission is listed in each endpoint's documentation.
`404`	Not Found	The requested resource does not exist or is not accessible to the current user.	Verify the resource ID in the URL path. Ensure you are querying within the correct organization scope.
`409`	Conflict	A resource with the same unique identifier already exists.	Check for duplicate emails, slugs, or names. Use a unique value.
`422`	Unprocessable Entity	The request was well-formed but contained semantic errors.	Review the validation error messages in the response body for specific field issues.
`429`	Too Many Requests	Rate limit exceeded. You are sending too many requests.	Implement exponential backoff. Reduce request frequency. Check the Retry-After header for wait time.
`500`	Internal Server Error	An unexpected error occurred on the server.	Retry the request after a brief delay. If the error persists, contact support with the request ID.

Best Practices

Always check the HTTP status code before parsing the response body.
Handle 401 errors by refreshing the access token using your refresh token, then retrying the request.
Implement exponential backoff for 429 and 500 errors.
Log the full error response (including message) for debugging purposes.
Never expose raw error messages to end users in production — map them to user-friendly messages.