Error Handling

Understand API error responses and how to handle them.

Error Format

All error responses follow the same format:

jsonJSON
 1{
 2  "error": "Human-readable error message"
 3}

HTTP Status Codes

CodeDescriptionCommon causes
400Bad RequestMissing required fields, invalid parameters
401UnauthorizedMissing or invalid API key
403ForbiddenInsufficient permissions for the operation
404Not FoundResource doesn't exist or doesn't belong to your company
500Internal ErrorServer-side error

Handling Errors with the SDK

The SDK throws typed errors that include the HTTP status code and error message:

typescriptTypeScript
 1import Corebill from '@corebill/sdk';
 2
 3const corebill = new Corebill({ apiKey: 'sk_live_...' });
 4
 5try {
 6  const customer = await corebill.customers.retrieve('cus_nonexistent');
 7} catch (error) {
 8  if (error instanceof Error) {
 9    console.error(error.message); // "Customer not found"
10  }
11}

Common Errors

Missing company_id

jsonJSON
 1// 400
 2{ "error": "company_id query parameter is required" }

Invalid API key

jsonJSON
 1// 401
 2{ "error": "Invalid API key" }

Insufficient permissions

jsonJSON
 1// 403
 2{ "error": "Insufficient permissions. Write access required." }

Resource not found

jsonJSON
 1// 404
 2{ "error": "Customer not found" }

Missing required fields

jsonJSON
 1// 400
 2{ "error": "name is required" }

Invalid status value

jsonJSON
 1// 400
 2{ "error": "Invalid status. Must be one of: draft, sent, viewed, paid, overdue, cancelled" }

Business rule violations

jsonJSON
 1// 400
 2{ "error": "Cannot delete a paid invoice" }

Best Practices

  • Always check the HTTP status code before parsing the response body
  • Use the error message for debugging, not for programmatic logic
  • Implement retry logic with exponential backoff for 500 errors
  • Log error responses for troubleshooting
PaginationMCP Server