​
Error Responses

The API uses RFC 9457 Problem Details for HTTP APIs for error responses, with content type application/problem+json. All error responses follow a consistent structure designed to provide clear, actionable information about what went wrong.

​
Error Structure

All error responses use the following structure: 
{
  "title": "Error Title",
  "status": 400,
  "detail": "Human-readable explanation of the problem",
  "errors": [
    {
      "location": "body.field_name",
      "message": "Specific error message",
      "value": "problematic_value"
    }
  ]
}

​
Fields

  • title: A short, human-readable summary of the problem type
  • status: The HTTP status code
  • detail: A human-readable explanation specific to this occurrence of the problem
  • errors (optional): An array of detailed error information, including:
    • location: Where the error occurred (e.g., body.items[3].tags or path.user-id)
    • message: Specific error message text
    • value: The problematic value that caused the error

​
Common Error Codes

​
400 Bad Request

Returned when the request cannot be processed due to malformed syntax, invalid JSON, or other client errors. 
{
  "title": "Bad Request",
  "status": 400,
  "detail": "validation failed",
  "errors": [
    {
      "message": "invalid character ',' looking for beginning of value",
      "location": "body",
      "value": "{\n  \"field_name\":,\n  \"another_field\": true\n}"
    }
  ]
}

​
401 Unauthorized

Returned when authentication is required but has failed or not been provided. The API supports multiple authentication methods, and different failure modes will return specific error messages. 
{
  "title": "Unauthorized",
  "status": 401,
  "detail": "Unauthorized: invalid authorization header",
  "errors": [
    {
      "message": "invalid authorization header",
      "location": "authorization"
    }
  ]
}

​
Common 401 Reasons

  • malformed authorization header: The Authorization header doesn’t follow the expected Bearer <token> format
  • invalid authorization header: The provided token is invalid, expired, or cannot be parsed
  • expired jwt: The JWT token has passed its expiration time and is no longer valid
  • application not found: The application referenced in the token doesn’t exist
  • application not active: The application exists but is not in an active state

​
403 Forbidden

Returned when the authenticated user or application lacks permission to access the requested resource or perform the requested action. 
{
  "title": "Forbidden",
  "status": 403,
  "detail": "Nutrition Records are not enabled for this application"
}

​
413 Request Entity Too Large

Returned when the request payload exceeds the maximum allowed size. The API limits request payloads to 10 MB. 
{
  "title": "Request Entity Too Large",
  "status": 413,
  "detail": "request body is too large limit=10485760 bytes"
}

​
422 Unprocessable Entity

Returned when the request is syntactically correct but contains validation errors. This includes schema validation failures, business rule violations, and data consistency issues. 
{
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "validation failed",
  "errors": [
    {
      "message": "expected value to be one of \"option1, option2, option3\"",
      "location": "body.field_name",
      "value": "invalid_option"
    },
    {
      "message": "field is required",
      "location": "body.required_field"
    }
  ]
}

​
500 Internal Server Error

Returned when an unexpected server-side error occurs. In production environments, sensitive error details are encrypted and replaced with a reference code that can be shared with support. 
{
  "title": "Internal Server Error",
  "status": 500,
  "detail": "Internal error at 1754296226: Share the following reference code with support: o8XIyE2aubQXVvgbiK6jDRjmJAdZRl9na1PBOm7tq_5Vi0o53ZHMzBc9JxUQfuNHcSLt7jEXnrMIrxRjrSFQBC9-BfwEVPEc5JqNueh9egsodrxmCsnzoD6EaKJoH2QbEup_pBuVQZNQIRzfssluj3jbuLmdCNnBJ86ygiM_V0pvNnPBsrNWXZj1uQ"
}
Note: When you encounter a 500 error, please share the reference code with our support team. This encrypted reference contains the technical details needed to diagnose and resolve the issue while protecting sensitive system information.

​
Error Handling Best Practices

  1. Check the status field to determine the error category
  2. Read the detail field for a human-readable explanation
  3. Process the errors array for specific validation failures
  4. Use the location field to identify which input fields need correction
  5. For 400 errors, review the errors array to identify the specific field that caused the error
  6. For 401 errors, check your authentication credentials and token validity
  7. For 413 errors, reduce your payload size to under 10 MB
  8. For 422 errors, review each item in the errors array to fix validation issues
  9. For 500 errors, save the reference code and contact support

​
Exhaustive Error Reporting

The API strives to return exhaustive errors whenever possible to prevent frustration from repeated failed requests. When multiple validation errors occur, all detected issues are included in a single response rather than failing on the first error encountered.