Error codes

Every error returns a JSON body whose error object holds code, message and request_id. Codes are stable; match on code, never on message. 402 means a billing problem (quota or payment) and is fixed with money; 429 means you are going too fast and is fixed by waiting Retry-After seconds.

Code	HTTP status	Message	Remediation
`invalid_body`	400	Request body must be valid JSON	Send valid JSON with Content-Type: application/json. house_number is a string, not a number.
`invalid_idempotency_key`	400	Idempotency-Key must be 1-255 visible ASCII characters	Send a unique value of 1-255 visible ASCII characters (for example a UUID).
`idempotency_key_reused`	422	This Idempotency-Key was already used with a different request body	Use a new key for a different body; replay the exact same body only with the same key.
`invalid_parameter`	400	Invalid or out-of-range parameter	Check the bounds: limit between 1 and 25 (autocomplete, search); range and group only with the documented values (usage).
`invalid_postal_code`	400	Postal code must be exactly 6 digits	Send exactly 6 digits, no spaces.
`invalid_query`	400	Query must be at least 2 characters	Send q with at least 2 characters.
`missing_address`	400	Provide either 'address' (structured) or 'freeform' (string)	Fill in one of the two fields.
`ambiguous_input`	400	Provide either 'address' or 'freeform', not both	Send a single address format.
`missing_locality`	400	locality is required	Add locality to the request body.
`house_number_requires_street`	400	house_number requires street	Send street together with house_number.
`invalid_house_number`	400	house_number must not be empty	Omit the field or send a non-empty number (string).
`missing_file_url`	400	file_url is required	Add file_url for the batch job.
`invalid_callback_url`	400	options.callback_url must be an https URL on a public host	Use a public https URL; private, loopback and link-local targets are rejected.
`field_too_long`	400	Text fields must be at most 256 characters	Shorten the field named in the message.
`missing_credentials`	401	Authentication required	Send Authorization: Bearer YOUR_API_KEY on every request.
`invalid_api_key`	401	Invalid or revoked API key	Rotate the key in the dashboard and update your secret store.
`quota_exceeded`	402	Monthly request quota exceeded — upgrade your plan to continue	Plans without overage stop at the monthly quota. Upgrade or wait for the reset (X-Posty-Period-Resets-At header). Do not auto-retry.
`payment_required`	402	Payment overdue — please update your payment method to continue	Update the payment method in the dashboard (X-Posty-Grace-Period-Ends header).
`forbidden`	403	Access denied	The resource belongs to another organization; use a key of the right organization.
`subscription_suspended`	403	Subscription suspended due to non-payment	Settle the overdue invoice in the dashboard.
`not_found`	404	The requested resource does not exist	Check the id you sent.
`postal_code_not_found`	404	No data found for the requested postal code	Check the postal code or use search.
`locality_not_found`	404	Locality not found	Check the locality name and county.
`method_not_allowed`	405	Method not allowed	Use the HTTP method documented for the endpoint.
`job_not_complete`	409	Job is not yet complete	Poll the job status until it is done.
`results_expired`	410	Results have been deleted after the retention period	Results are kept 30 days after completion; resubmit the job.
`payload_too_large`	413	Request body exceeds 64 KiB	Send a smaller body or use batch.
`rate_limit_exceeded`	429	Rate limit exceeded, please slow down	Wait the Retry-After seconds and honour the X-RateLimit-* headers.
`internal_error`	500	Internal server error	Send request_id to support@posty.ro for investigation.
`request_timeout`	504	Request timed out — please retry	Retry idempotent requests. POST /v1/addresses/batch is not atomic: a retry may create a duplicate job.