Error codes
Every error returns JSON with code, message and request_id. The table below lists the codes and recommended fixes.
| Code | HTTP status | Message | Remediation |
|---|---|---|---|
auth_required | 401 | Missing Authorization header. | Send Authorization: Bearer YOUR_API_KEY on every request. |
invalid_api_key | 401 | The API key is invalid or has been revoked. | Rotate the key in the dashboard and update your secret store. |
forbidden | 403 | This key is not allowed to call this endpoint. | Check the key scopes in the dashboard or issue a broader-scoped key. |
rate_limited | 429 | You exceeded the per-minute request rate. | Honour the Retry-After and X-RateLimit-* headers, or upgrade plan. |
quota_exceeded | 402 | Monthly plan quota exhausted. | Upgrade your plan or wait for the next billing period. |
validation_failed | 422 | The request body failed validation. | See the details field in the response for the invalid fields. |
not_found | 404 | The requested resource does not exist. | Check the id or postal code you sent. |
idempotency_conflict | 409 | Idempotency-Key replayed with a different body. | Use a fresh key for distinct requests or replay the exact same body. |
service_unavailable | 503 | The service is temporarily unavailable. | Retry with exponential backoff. See status.posty.ro for incidents. |
internal_server_error | 500 | Unexpected server error on our side. | Send request_id to support@posty.ro for investigation. |