BluebulbAPI
    Using the API

    Responses & errors

    Every response — success or failure — is JSON in the same envelope, so you can always check one field to know whether a call worked.

    Successful responses

    status
    true.
    statusCode
    The HTTP status, 200 for reads and 201 for creates.
    message
    A short description, e.g. Rates retrieved.
    data
    The result. Its shape is documented on each endpoint.
    201 Created
    {
  "data": {
    "conversionId": "6f1c2b7e-4d2a-4c8e-9b1a-2f7d3e8a9c10",
    "status": "processing",
    "proposedCompletionTime": "2026-09-22T15:03:10.512+01:00"
  },
  "message": "Conversion request received",
  "status": true,
  "statusCode": 201
}

    Error responses

    status
    false.
    message
    What went wrong, readable by people. The HTTP status tells you the category.
    data
    Extra detail, when there is any. For validation failures, data.errors lists every problem.
    400 Bad Request
    {
  "status": false,
  "message": "Insufficient funds"
}
    400 Bad Request (validation)
    {
  "status": false,
  "message": "Validation failed",
  "data": {
    "errors": [
      "amount must be a positive number",
      "customerReference should not be empty"
    ]
  }
}

    Status codes

    200 OK
    The request succeeded.
    201 Created
    A conversion or payout was created.
    400 Bad Request
    The request is invalid or breaks a business rule (validation, insufficient funds, unsupported pair, limits). The message says which. Don't retry unchanged.
    403 Forbidden
    Authentication failed: API key, IP allowlist or signature. See Authentication.
    404 Not Found
    The conversion or payout doesn't exist on your business.
    409 Conflict
    The payout clashes with an existing one: its customerReference is already used or still being processed, or its conversionId already funds another payout.
    429 Too Many Requests
    Rate limit reached. Back off and retry.
    500 Internal Server Error
    Something failed on Orbita's side. The message is always Sorry, we are unable to process your request.
    503 Service Unavailable
    A dependency is temporarily unavailable. Retry with backoff.

    Retrying safely

    • Only retry 429, 500, 503 and network timeouts. Sign every retry again — a signature can only be used once.
    • Payouts are safe to retry: resend with the same customerReference. A 409 means a payout with that reference already exists — not necessarily the one you meant to send. Fetch it with Get a payout and check its amount, currency and beneficiary match your attempt before treating the retry as successful.
    • Conversions have no idempotency key, so a 500, 503 or timeout doesn't tell you whether the conversion was created. Check List conversions for it before sending the request again.

    Errors any endpoint can return

    403
    Forbidden resource
    Missing or invalid x-api-key.
    403
    This IP address (203.0.113.10) is not whitelisted for this API key
    Request from an address not on your allowlist.
    403
    Invalid request signature
    Signature doesn't match. See Request signing.
    429
    You're making requests a little too quickly. Please wait a moment and try again.
    Rate limit reached.
    500
    Sorry, we are unable to process your request
    Unexpected error on Orbita's side.

    The full list of authentication errors is on Authentication.