Fundamentals
Errors
Error format (RFC 9457) and the most common types.
Errors follow RFC 9457 (application/problem+json). The type field identifies the error; errors lists the fields at fault.
{
"type": "https://docs.pineplechain.com/problems/validation-error",
"title": "Validation error",
"status": 422,
"detail": "amount: must be at least 0.001",
"instance": "/v1/invoices",
"request_id": "req_6c1d0b7e-2f4a-4c3e-9d1b-7a5e8f2c4b10",
"errors": [{ "path": "amount", "message": "must be at least 0.001" }]
}Common types
| Status | type | When |
|---|---|---|
| 400 | bad-request, malformed-json | Invalid body, or Idempotency-Key missing where required. |
| 401 | unauthorized | Missing, invalid or revoked key. |
| 402 | fees-overdue | Overdue fee invoice (production). |
| 403 | forbidden, kyb-required | Not allowed, or the business is not verified yet. |
| 404 | not-found | Does not exist, or belongs to another business. |
| 409 | invalid-state-transition, escrow-expired, mode-mismatch | The action is not valid in the current status, the escrow expired, or the key belongs to the other environment. |
| 422 | validation-error, idempotency-key-reused | Invalid or unknown field, or a reused idempotency key. |
| 429 | rate-limited | More than 120 calls per minute. |
| 502 / 503 | ledger-error, platform-not-ready | Temporary XRPL or platform failure. Try again. |
Unknown fields in the body or the query string are rejected with 422. That catches typos early.