API reference

Errors

Every failure has an HTTP status, a human-readable error, and an error_code to branch on. Show error to your staff; code against error_code.

Error codes

HTTP	`error_code`	Cause and what to do
`400`	`invalid_json`	The body isn't a JSON object. Check the `Content-Type` and serialisation.
`400`	`invalid_action`	The `action` is missing or unknown.
`401`	`missing_api_key`	No `Authorization: Bearer` header was sent.
`401`	`invalid_api_key`	The key is wrong, revoked, or from the other environment.
`403`	`merchant_inactive`	Your merchant account isn't active yet. Contact Cashwo support.
`404`	`not_found`	No agreement or payment with that id in your account.
`405`	`method_not_allowed`	Use `POST`.
`409`	`idempotency_key_reused`	That Idempotency-Key was already used with a different body. Use a new key.
`409`	`idempotency_in_progress`	The first request with that key is still running. Retry shortly.
`409`	`invalid_status_change`	The agreement's status doesn't allow that change. Fetch it and check.
`409`	`status_changed`	The agreement changed while you were changing it. Fetch it and try again.
`422`	`validation_failed`	`error` lists every problem; each message names the field.
`422`	`invalid_idempotency_key`	Keys are 1–100 characters: letters, digits, `- _ : .`
`500`	`internal_error`	A problem at Cashwo. Retry with the same Idempotency-Key.
`502`	`bank_rejected`	The payment network refused the change.
`504`	`bank_timeout`	The payment network didn't answer. Fetch the agreement before retrying.

Typical messages from create_agreement:

Limit payment references to 22 characters. — payment_ref must be 2–21 characters.
merchant_reference must be at least 2 characters long. — 2–21 characters.
Invalid Name. — letters and spaces only, up to 30 characters.
Invalid Phone Number. … — an Australian mobile is required.
Invalid Email.
Invalid frequency. — one value from the list.
amount must be greater than 0.
agreement_end_date must be a valid date (YYYY-MM-DD), today or later.
One-time agreements are not enabled for this merchant. — ask Cashwo support.

Retry 5xx responses and network timeouts, with the same Idempotency-Key and a growing delay.
Don't retry 4xx responses unchanged; fix the request first. The exception is idempotency_in_progress.
After bank_timeout, read the agreement: the change may have gone through.