Error Codes

The Deliverty Hub API uses standard HTTP status codes combined with structured error responses to communicate problems.

Error Response Format

All error responses follow this JSON structure:

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request",
  "details": [
    {
      "field": "email",
      "message": "email must be a valid email address"
    }
  ]
}

HTTP Status Codes

Code	Meaning	When It Happens
200	OK	Request succeeded.
201	Created	Resource created successfully.
400	Bad Request	Validation error, missing fields, or malformed body.
401	Unauthorized	Missing or invalid x-api-key header.
403	Forbidden	Valid key but insufficient permissions for the action.
404	Not Found	Resource doesn't exist or is not in your organization.
409	Conflict	Duplicate resource or invalid state transition (e.g., completing a cancelled task).
422	Unprocessable Entity	Semantic error — data is valid JSON but doesn't make business sense.
429	Too Many Requests	Rate limit exceeded. See Rate Limits.
500	Internal Server Error	Unexpected server error. Contact support if persistent.

Common Error Scenarios

Authentication Errors

Scenario	Status	Message
Missing API key header	401	API key is required
Invalid API key	401	Invalid API key
Channel is suspended	403	Channel is suspended
Channel is inactive	403	Channel is inactive

Task Errors

Scenario	Status	Message
Task not found	404	Task not found
Invalid status transition	409	Cannot transition from {current} to {target}
Missing required fields	400	Validation failed with field details
Invalid task type	400	taskType must be one of: job, pickup, delivery, cash_collection, cash_drop

Webhook Errors

Scenario	Status	Message
Invalid URL format	400	url must be a valid URL
No events specified	400	At least one event is required
Subscription not found	404	Webhook subscription not found