Skip to main content
All Partner API errors return a consistent JSON format with an HTTP status code indicating the error category.

​
Error format

{
  "success": false,
  "error": "Human-readable error message"
}

​
HTTP status codes

StatusMeaningCommon causes
400Bad requestMissing required fields, invalid field values, malformed JSON
401UnauthorizedMissing x-contro-api-key header, invalid or expired API key
404Not foundResource does not exist or belongs to a different partner
429Rate limitedExceeded 1,000 requests per minute
500Internal server errorUnexpected server issue — retry with backoff

​
Troubleshooting

​
400 Bad request

The request body or query parameters are invalid. Check:
  • Required fields are present (externalUserId, firstName, lastName, email for cardholders)
  • Field types match the schema (e.g., limit is a number, not a string)
  • Email addresses are valid format
  • The request body is valid JSON with Content-Type: application/json

​
401 Unauthorized

The API key is missing or invalid. Check:
  • The x-contro-api-key header is present: x-contro-api-key: sk_test_...
  • The key prefix matches your environment (sk_test_* for sandbox, sk_live_* for production)
  • The key has not been revoked or rotated

​
404 Not found

The requested resource does not exist. Check:
  • The resource ID is correct
  • The resource belongs to your partner account (you cannot access other partners’ resources)
  • The resource has not been deleted

​
429 Rate limited

You’ve exceeded the rate limit of 1,000 requests per minute. Handle:
  • Read the Retry-After header to determine when to retry
  • Implement exponential backoff in your client
  • Consider batching operations or caching responses

​
500 Internal server error

An unexpected error occurred on the server. Handle:
  • Retry the request after a short delay (1–5 seconds)
  • Use exponential backoff for repeated failures
  • If the error persists, contact support with the request details

​
Best practices

  • Check the error message — it describes what went wrong in human-readable terms
  • Use idempotency keys — when issuing cards, pass idempotencyKey to safely retry failed requests
  • Implement retry logic — for 429 and 500 errors, retry with exponential backoff
  • Log error responses — capture the full response for debugging