Docs
Search the docs
Find a page in the docs

Concepts

Errors

HTTP status codes, the error body, and what to do about each one.

Camel uses standard HTTP status codes. 2xx means the request worked, 4xx means something in the request needs fixing, and 5xx means a provider or Camel couldn't complete it.

Error body

Errors return a JSON body with a detail message:

409 Conflict
{
  "detail": "Refund amount exceeds the unreserved payment balance"
}

Validation errors (422) list each invalid field instead:

422 Unprocessable Content
{
  "detail": [
    {
      "type": "greater_than",
      "loc": ["body", "amount"],
      "msg": "Input should be greater than 0",
      "input": 0
    }
  ]
}

Status codes

StatusMeaning
200 201Success.
202 The provider's answer is uncertain. The resource has status unknown and Camel will settle it. See Idempotency.
400A malformed header or cursor.
401The API key is missing, malformed, or revoked.
402 Production only: your Camel invoice is past due. Pay it from Billing.
404The resource doesn't exist in this key's environment.
409 The request conflicts with the resource's state (a refund larger than what's left) or with an idempotency key already in use.
422 The body is invalid, or the connection can't do what you asked.
429 Too many requests. See Rate limits.
502 The provider returned an error. The body is the resource, with status failed.
503Exchange rates are temporarily unavailable.

Declined payments

A declined card is not an HTTP error. The request returns 201 and the payment has status: "rejected". The provider's own status is in provider_status. When Camel couldn't reach a result, the payment carries a failure object:

failure
{
  "failure": {
    "code": "unknown",
    "provider_code": null
  }
}

failure.code is one of insufficient_funds, invalid_card, expired_card, security_code_invalid, fraud_suspected, authentication_required, invalid_credentials, provider_unavailable, rate_limited, duplicate_operation, or unknown.

Request ids

Every response has an X-Request-ID header. Include it when you contact support. You can also send your own X-Request-ID (8 to 64 letters, digits, - or _) and Camel will use it.