Errors

The API returns consistent error responses with an HTTP status code and a JSON body containing an error code and human-readable message.

Error Response Format

All errors follow this structure:

{
  "error": {
    "code": "not_found",
    "message": "Lead not found"
  }
}

Field	Type	Description
`error.code`	string	A machine-readable error code
`error.message`	string	A human-readable description of the error

HTTP Status Codes

Code	Status	Description
`200`	OK	Request succeeded
`201`	Created	Resource successfully created
`400`	Bad Request	Invalid request body or missing required parameters
`401`	Unauthorized	Missing, invalid, or revoked API key
`403`	Forbidden	API key does not have permission for this action
`404`	Not Found	The requested resource does not exist
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Error	An unexpected error occurred on the server

Error Code Reference

Error Code	HTTP Status	Description
`unauthorized`	401	Invalid or missing API key
`bad_request`	400	Invalid request parameters
`not_found`	404	Resource not found
`rate_limited`	429	Rate limit exceeded
`internal`	500	Server error

Common Error Scenarios

Missing Authorization Header

curl -X GET "https://kdjmltmhxvvmiuehafgl.supabase.co/functions/v1/api-gateway/v1/leads"

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid Authorization header. Use: Bearer rchd_live_xxx"
  }
}

Invalid JSON Body

curl -X POST \
  "https://kdjmltmhxvvmiuehafgl.supabase.co/functions/v1/api-gateway/v1/leads" \
  -H "Authorization: Bearer rchd_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d 'invalid json'

{
  "error": {
    "code": "bad_request",
    "message": "Invalid JSON body"
  }
}

Resource Not Found

{
  "error": {
    "code": "not_found",
    "message": "Lead not found"
  }
}

Always check the error.code field programmatically rather than parsing the message string, as messages may change over time.

Getting started

Popular tools

Errors

Errors

Error Response Format

HTTP Status Codes

Error Code Reference

Common Error Scenarios

Missing Authorization Header

Invalid JSON Body

Resource Not Found

​Errors

​Error Response Format

​HTTP Status Codes

​Error Code Reference

​Common Error Scenarios

​Missing Authorization Header

​Invalid JSON Body

​Resource Not Found

Errors

Error Response Format

HTTP Status Codes

Error Code Reference

Common Error Scenarios

Missing Authorization Header

Invalid JSON Body

Resource Not Found