| HTTP | Code | Meaning | Cause | Solution |
|---|
| 401 | unauthorized | Authentication failed. | Missing/invalid API key or HMAC signature. | Rebuild the canonical string and rotate compromised keys. |
| 403 | forbidden | Key cannot access the resource. | Wrong connection/application. | Use the correct CRM connection key. |
| 404 | not_found | Property or route was not found. | Unknown external_ref or unsupported endpoint. | Check the reference and API Reference page. |
| 405 | method_not_allowed | Wrong HTTP method. | Endpoint does not support the verb. | Use the documented method. |
| 422 | validation_failed | Payload did not pass validation. | Missing required canonical fields or bad values. | Fix field errors and retry with the same idempotency key only if safe. |
| 409 | duplicate_request | Idempotent request already completed. | Same event/request id was replayed. | Use returned response or send a new event id for a new change. |
| 409 | already_processing | Same request is in progress. | Concurrent retry. | Wait and retry later. |
| 429 | rate_limited | Limit exceeded. | Too many calls for the key/application. | Use backoff and inspect Rate Limits. |
| 413 | payload_too_large | Request body too large. | Large JSON or media embedded in payload. | Send URLs for media instead of binary data. |
| 500 | internal_error | Unexpected processing error. | Server/runtime failure. | Retry with backoff and contact support with request id. |
Example
{
"success": false,
"error": {
"code": "validation_failed",
"message": "property.display_address is required.",
"field": "property.display_address",
"request_id": "req-001",
"retryable": false
}
}