Error Handling

The Steward API uses standard HTTP status codes and returns structured error responses.

HTTP Status Codes

Code	Meaning
200	Success
201	Created
400	Bad Request - invalid parameters or request body
401	Unauthorized - missing or invalid API key
403	Forbidden - valid key but insufficient permissions
404	Not Found - resource doesn’t exist or doesn’t belong to your account
500	Internal Server Error

Validation failures return 400, not 422.

Error Response Format

Error responses include a message field describing the issue:

{
  "statusCode": 400,
  "message": "Only pending applications can be submitted",
  "error": "Bad Request"
}

Common Errors

Invalid API Key

{
  "statusCode": 401,
  "message": "Invalid API key"
}

Verify your API key is correct and active. Keys that have been revoked will return this error.

Resource Not Found

{
  "statusCode": 404,
  "message": "Application not found"
}

The resource either doesn’t exist or doesn’t belong to your account. The API will not reveal whether a resource exists in another account.

Validation Errors

{
  "statusCode": 400,
  "message": ["email must be an email", "firstName should not be empty"],
  "error": "Bad Request"
}

The message field may be an array when multiple validation errors occur.

Pagination Cursor Errors

Cursor tokens are tied to the sort direction and field they were issued under. Reusing a cursor under a different order or orderBy is rejected with 400:

Message	Cause
Invalid pagination cursor	The token is malformed or wasn’t issued by this API.
Pagination cursor direction does not match sort order	You changed order mid-pagination. Drop the cursor and start over.
Pagination cursor sort field does not match requested orderBy	You changed orderBy mid-pagination. Drop the cursor and start over.

See the Pagination guide for the cursor lifecycle.

Tip: Always check the HTTP status code first, then read the message field for details. Build your error handling to gracefully handle both string and array message values.