Platform

Error Handling

Understand API error responses and how to handle them.

Error Format

All error responses follow the same format:

JSON

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

HTTP Status Codes

Code	Description	Common causes
`400`	Bad Request	Missing required fields, invalid parameters
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	Insufficient permissions for the operation
`404`	Not Found	Resource doesn't exist or doesn't belong to your company
`500`	Internal Error	Server-side error

Handling Errors with the SDK

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

TypeScript

 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

API key not scoped to a company

JSON

 1// 401
 2{
 3  "error": {
 4    "type": "authentication_error",
 5    "code": "api_key_company_missing",
 6    "message": "API key is not scoped to a company. Re-issue the key from the dashboard."
 7  }
 8}

Invalid API key

JSON

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

Insufficient permissions

JSON

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

Resource not found

JSON

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

Missing required fields

JSON

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

Invalid status value

JSON

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

Business rule violations

JSON

 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

Pagination MCP Server