Response shape
Every response uses the same envelope. On success, payload holds the result and error is null.
{
"payload": { },
"error": null
}
payload is null and error carries a machine readable code, a human readable message, a requestId, and, for validation failures, per field details.
{
"payload": null,
"error": {
"code": "E_VALIDATION_FAILED",
"message": "one or more fields are invalid",
"requestId": "3D2mMaLHsT60sI5qyeHuBlS9TEM",
"fields": {
"doolaCustomerId": {
"code": "E_CUSTOMER_ID_REQUIRED",
"message": "customer id is required"
}
}
}
}
Branch on error.code, not on message. Codes are stable; messages may change.
Global error reference
These can be returned by any endpoint. Endpoint specific codes are documented in the API reference.
| HTTP | Code | Meaning |
|---|
| 400 | E_IDEMPOTENCY_KEY_REQUIRED | Missing Idempotency-Key header |
| 400 | E_IDEMPOTENCY_KEY_TOO_LONG | Idempotency-Key exceeds the max length |
| 400 | E_MALFORMED_JSON | Request body is not parseable JSON |
| 400 | E_REQUEST_BODY_INVALID | Body is missing, malformed, or the wrong shape |
| 401 | E_AUTH_MISSING | No Authorization header present |
| 401 | E_AUTH_INVALID | Invalid or expired key, or a key used on the wrong environment |
| 403 | E_TENANT_SUSPENDED | Partner tenant is suspended; writes are rejected |
| 405 | E_METHOD_NOT_ALLOWED | HTTP method not allowed for this resource |
| 409 | E_IDEMPOTENCY_IN_PROGRESS | Same idempotency key is still processing |
| 409 | E_IDEMPOTENCY_KEY_REUSED | Same idempotency key used with a different body |
| 500 | E_INTERNAL | Unexpected server error |
| 503 | E_SEARCH_UNAVAILABLE | Search backend unavailable (list and search endpoints) |
