# Error Guide

All public API errors use one shape:

```json
{
  "success": false,
  "error": {
    "code": "validation_failed",
    "message": "Validation failed",
    "details": [],
    "request_id": "req-001",
    "retryable": false
  }
}
```

## Error Codes

| Code | Meaning | Retry |
|---|---|---|
| `unauthorized` | Missing, malformed, expired, or invalid authentication. | No |
| `forbidden` | Authenticated but not permitted for this connection or IP. | No |
| `not_found` | The property does not exist for the authenticated connection. | No |
| `method_not_allowed` | HTTP method is not supported for the endpoint. | No |
| `validation_failed` | Payload or headers failed validation. | No |
| `duplicate_request` | The same completed request was submitted again. | No |
| `already_processing` | The same request is currently being processed. | Yes |
| `rate_limited` | The connection exceeded the rate limit. | Yes |
| `payload_too_large` | Request body exceeded the public size limit. | No |
| `conflict` | The request conflicts with current processing or ownership state. | Depends |
| `internal_error` | Internal processing failed. | Yes |

## Validation Details

Validation fields use public names only, for example:

```text
property.external_ref
property.display_address
property.price
property.media_image_00
property.media_document_00
```